Skip to content

Commit 19943c1

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: added API for changelogs
docs: clarified semantic of the streaming APIs PiperOrigin-RevId: 404659561
1 parent 180ec36 commit 19943c1

4 files changed

Lines changed: 220 additions & 37 deletions

File tree

‎google/cloud/dialogflow/cx/v3beta1/BUILD.bazel‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ proto_library(
2424
"advanced_settings.proto",
2525
"agent.proto",
2626
"audio_config.proto",
27+
"changelog.proto",
2728
"deployment.proto",
2829
"entity_type.proto",
2930
"environment.proto",
@@ -108,6 +109,7 @@ java_gapic_test(
108109
name = "cx_java_gapic_test_suite",
109110
test_classes = [
110111
"com.google.cloud.dialogflow.cx.v3beta1.AgentsClientTest",
112+
"com.google.cloud.dialogflow.cx.v3beta1.ChangelogsClientTest",
111113
"com.google.cloud.dialogflow.cx.v3beta1.DeploymentsClientTest",
112114
"com.google.cloud.dialogflow.cx.v3beta1.EntityTypesClientTest",
113115
"com.google.cloud.dialogflow.cx.v3beta1.EnvironmentsClientTest",

‎google/cloud/dialogflow/cx/v3beta1/changelog.proto‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
// Copyright 2021 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package google.cloud.dialogflow.cx.v3beta1;
18+
19+
import "google/api/annotations.proto";
20+
import "google/api/client.proto";
21+
import "google/api/field_behavior.proto";
22+
import "google/api/resource.proto";
23+
import "google/protobuf/struct.proto";
24+
import "google/protobuf/timestamp.proto";
25+
26+
option cc_enable_arenas = true;
27+
option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3Beta1";
28+
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3beta1;cx";
29+
option java_multiple_files = true;
30+
option java_outer_classname = "ChangelogProto";
31+
option java_package = "com.google.cloud.dialogflow.cx.v3beta1";
32+
option objc_class_prefix = "DF";
33+
option ruby_package = "Google::Cloud::Dialogflow::CX::V3beta1";
34+
35+
// Service for managing [Changelogs][google.cloud.dialogflow.cx.v3beta1.Changelog].
36+
service Changelogs {
37+
option (google.api.default_host) = "dialogflow.googleapis.com";
38+
option (google.api.oauth_scopes) =
39+
"https://www.googleapis.com/auth/cloud-platform,"
40+
"https://www.googleapis.com/auth/dialogflow";
41+
42+
// Returns the list of Changelogs.
43+
rpc ListChangelogs(ListChangelogsRequest) returns (ListChangelogsResponse) {
44+
option (google.api.http) = {
45+
get: "/v3beta1/{parent=projects/*/locations/*/agents/*}/changelogs"
46+
};
47+
option (google.api.method_signature) = "parent";
48+
}
49+
50+
// Retrieves the specified Changelog.
51+
rpc GetChangelog(GetChangelogRequest) returns (Changelog) {
52+
option (google.api.http) = {
53+
get: "/v3beta1/{name=projects/*/locations/*/agents/*/changelogs/*}"
54+
};
55+
option (google.api.method_signature) = "name";
56+
}
57+
}
58+
59+
// The request message for [Changelogs.ListChangelogs][google.cloud.dialogflow.cx.v3beta1.Changelogs.ListChangelogs].
60+
message ListChangelogsRequest {
61+
// Required. The agent containing the changelogs.
62+
// Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
63+
string parent = 1 [
64+
(google.api.field_behavior) = REQUIRED,
65+
(google.api.resource_reference) = {
66+
child_type: "dialogflow.googleapis.com/Changelog"
67+
}
68+
];
69+
70+
// The filter string. Supports filter by user_email, resource, type and
71+
// create_time. Some examples:
72+
// 1. By user email:
73+
// user_email = "[email protected]"
74+
// 2. By resource name:
75+
// resource = "projects/123/locations/global/agents/456/flows/789"
76+
// 3. By resource display name:
77+
// display_name = "my agent"
78+
// 4. By action:
79+
// action = "Create"
80+
// 5. By type:
81+
// type = "flows"
82+
// 6. By create time. Currently predicates on `create_time` and
83+
// `create_time_epoch_seconds` are supported:
84+
// create_time_epoch_seconds > 1551790877 AND create_time <=
85+
// 2017-01-15T01:30:15.01Z
86+
// 7. Combination of above filters:
87+
// resource = "projects/123/locations/global/agents/456/flows/789"
88+
// AND user_email = "[email protected]"
89+
// AND create_time <= 2017-01-15T01:30:15.01Z
90+
string filter = 2;
91+
92+
// The maximum number of items to return in a single page. By default 100 and
93+
// at most 1000.
94+
int32 page_size = 3;
95+
96+
// The next_page_token value returned from a previous list request.
97+
string page_token = 4;
98+
}
99+
100+
// The response message for [Changelogs.ListChangelogs][google.cloud.dialogflow.cx.v3beta1.Changelogs.ListChangelogs].
101+
message ListChangelogsResponse {
102+
// The list of changelogs. There will be a maximum number of items returned
103+
// based on the page_size field in the request. The changelogs will be ordered
104+
// by timestamp.
105+
repeated Changelog changelogs = 1;
106+
107+
// Token to retrieve the next page of results, or empty if there are no more
108+
// results in the list.
109+
string next_page_token = 2;
110+
}
111+
112+
// The request message for [Changelogs.GetChangelog][google.cloud.dialogflow.cx.v3beta1.Changelogs.GetChangelog].
113+
message GetChangelogRequest {
114+
// Required. The name of the changelog to get.
115+
// Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
116+
// ID>/changelogs/<Changelog ID>`.
117+
string name = 1 [
118+
(google.api.field_behavior) = REQUIRED,
119+
(google.api.resource_reference) = {
120+
type: "dialogflow.googleapis.com/Changelog"
121+
}
122+
];
123+
}
124+
125+
// Changelogs represents a change made to a given agent.
126+
message Changelog {
127+
option (google.api.resource) = {
128+
type: "dialogflow.googleapis.com/Changelog"
129+
pattern: "projects/{project}/locations/{location}/agents/{agent}/changelogs/{changelog}"
130+
};
131+
132+
// The unique identifier of the changelog.
133+
// Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
134+
// ID>/changelogs/<Changelog ID>`.
135+
string name = 1;
136+
137+
// Email address of the authenticated user.
138+
string user_email = 2;
139+
140+
// The affected resource display name of the change.
141+
string display_name = 7;
142+
143+
// The action of the change.
144+
string action = 11;
145+
146+
// The affected resource type.
147+
string type = 8;
148+
149+
// The affected resource name of the change.
150+
string resource = 3;
151+
152+
// The timestamp of the change.
153+
google.protobuf.Timestamp create_time = 4;
154+
}

‎google/cloud/dialogflow/cx/v3beta1/dialogflow_v3beta1.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ title: Dialogflow API
55

66
apis:
77
- name: google.cloud.dialogflow.cx.v3beta1.Agents
8+
- name: google.cloud.dialogflow.cx.v3beta1.Changelogs
89
- name: google.cloud.dialogflow.cx.v3beta1.Deployments
910
- name: google.cloud.dialogflow.cx.v3beta1.EntityTypes
1011
- name: google.cloud.dialogflow.cx.v3beta1.Environments
@@ -71,6 +72,10 @@ backend:
7172
rules:
7273
- selector: 'google.cloud.dialogflow.cx.v3beta1.Agents.*'
7374
deadline: 60.0
75+
- selector: google.cloud.dialogflow.cx.v3beta1.Changelogs.GetChangelog
76+
deadline: 60.0
77+
- selector: google.cloud.dialogflow.cx.v3beta1.Changelogs.ListChangelogs
78+
deadline: 60.0
7479
- selector: google.cloud.dialogflow.cx.v3beta1.Deployments.GetDeployment
7580
deadline: 60.0
7681
- selector: google.cloud.dialogflow.cx.v3beta1.Deployments.ListDeployments
@@ -140,6 +145,16 @@ authentication:
140145
canonical_scopes: |-
141146
https://www.googleapis.com/auth/cloud-platform,
142147
https://www.googleapis.com/auth/dialogflow
148+
- selector: google.cloud.dialogflow.cx.v3beta1.Changelogs.GetChangelog
149+
oauth:
150+
canonical_scopes: |-
151+
https://www.googleapis.com/auth/cloud-platform,
152+
https://www.googleapis.com/auth/dialogflow
153+
- selector: google.cloud.dialogflow.cx.v3beta1.Changelogs.ListChangelogs
154+
oauth:
155+
canonical_scopes: |-
156+
https://www.googleapis.com/auth/cloud-platform,
157+
https://www.googleapis.com/auth/dialogflow
143158
- selector: google.cloud.dialogflow.cx.v3beta1.Deployments.GetDeployment
144159
oauth:
145160
canonical_scopes: |-

‎google/cloud/dialogflow/cx/v3beta1/session.proto‎

Lines changed: 49 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ message DetectIntentResponse {
201201
// Multiple request messages should be sent in order:
202202
//
203203
// 1. The first message must contain
204-
// [session][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.session],
204+
// [session][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.session],
205205
// [query_input][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_input] plus optionally
206206
// [query_params][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_params]. If the client
207207
// wants to receive an audio response, it should also contain
@@ -261,21 +261,29 @@ message StreamingDetectIntentRequest {
261261
bool enable_partial_response = 5;
262262
}
263263

264-
// The top-level message returned from the `StreamingDetectIntent` method.
264+
// The top-level message returned from the
265+
// [StreamingDetectIntent][google.cloud.dialogflow.cx.v3beta1.Sessions.StreamingDetectIntent] method.
265266
//
266-
// Multiple response messages can be returned in order:
267+
// Multiple response messages (N) can be returned in order.
267268
//
268-
// 1. If the input was set to streaming audio, the first one or more messages
269-
// contain `recognition_result`. Each `recognition_result` represents a more
270-
// complete transcript of what the user said. The last `recognition_result`
271-
// has `is_final` set to `true`.
269+
// The first (N-1) responses set either the `recognition_result` or
270+
// `detect_intent_response` field, depending on the request:
272271
//
273-
// 2. If `enable_partial_response` is true, the following N messages
274-
// (currently 1 <= N <= 4) contain `detect_intent_response`. The first (N-1)
275-
// `detect_intent_response`s will have `response_type` set to `PARTIAL`.
276-
// The last `detect_intent_response` has `response_type` set to `FINAL`.
277-
// If `response_type` is false, response stream only contains
278-
// the final `detect_intent_response`.
272+
// * If the `StreamingDetectIntentRequest.query_input.audio` field was
273+
// set, and the `StreamingDetectIntentRequest.enable_partial_response`
274+
// field was false, the `recognition_result` field is populated for each
275+
// of the (N-1) responses.
276+
// See the [StreamingRecognitionResult][google.cloud.dialogflow.cx.v3beta1.StreamingRecognitionResult] message for details
277+
// about the result message sequence.
278+
//
279+
// * If the `StreamingDetectIntentRequest.enable_partial_response` field was
280+
// true, the `detect_intent_response` field is populated for each
281+
// of the (N-1) responses, where 1 <= N <= 4.
282+
// These responses set the [DetectIntentResponse.response_type][google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse.response_type] field
283+
// to `PARTIAL`.
284+
//
285+
// For the final Nth response message, the `detect_intent_response` is fully
286+
// populated, and [DetectIntentResponse.response_type][google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse.response_type] is set to `FINAL`.
279287
message StreamingDetectIntentResponse {
280288
// The output response.
281289
oneof response {
@@ -291,35 +299,39 @@ message StreamingDetectIntentResponse {
291299
// that is currently being processed or an indication that this is the end
292300
// of the single requested utterance.
293301
//
294-
// Example:
295-
//
296-
// 1. transcript: "tube"
297-
//
298-
// 2. transcript: "to be a"
299-
//
300-
// 3. transcript: "to be"
301-
//
302-
// 4. transcript: "to be or not to be"
303-
// is_final: true
304-
//
305-
// 5. transcript: " that's"
306-
//
307-
// 6. transcript: " that is"
308-
//
309-
// 7. message_type: `END_OF_SINGLE_UTTERANCE`
302+
// While end-user audio is being processed, Dialogflow sends a series of
303+
// results. Each result may contain a `transcript` value. A transcript
304+
// represents a portion of the utterance. While the recognizer is processing
305+
// audio, transcript values may be interim values or finalized values.
306+
// Once a transcript is finalized, the `is_final` value is set to true and
307+
// processing continues for the next transcript.
310308
//
311-
// 8. transcript: " that is the question"
312-
// is_final: true
309+
// If `StreamingDetectIntentRequest.query_input.audio.config.single_utterance`
310+
// was true, and the recognizer has completed processing audio,
311+
// the `message_type` value is set to `END_OF_SINGLE_UTTERANCE and the
312+
// following (last) result contains the last finalized transcript.
313313
//
314-
// Only two of the responses contain final results (#4 and #8 indicated by
315-
// `is_final: true`). Concatenating these generates the full transcript: "to be
316-
// or not to be that is the question".
314+
// The complete end-user utterance is determined by concatenating the
315+
// finalized transcript values received for the series of results.
317316
//
318-
// In each response we populate:
317+
// In the following example, single utterance is enabled. In the case where
318+
// single utterance is not enabled, result 7 would not occur.
319319
//
320-
// * for `TRANSCRIPT`: `transcript` and possibly `is_final`.
320+
// ```
321+
// Num | transcript | message_type | is_final
322+
// --- | ----------------------- | ----------------------- | --------
323+
// 1 | "tube" | TRANSCRIPT | false
324+
// 2 | "to be a" | TRANSCRIPT | false
325+
// 3 | "to be" | TRANSCRIPT | false
326+
// 4 | "to be or not to be" | TRANSCRIPT | true
327+
// 5 | "that's" | TRANSCRIPT | false
328+
// 6 | "that is | TRANSCRIPT | false
329+
// 7 | unset | END_OF_SINGLE_UTTERANCE | unset
330+
// 8 | " that is the question" | TRANSCRIPT | true
331+
// ```
321332
//
322-
// * for `END_OF_SINGLE_UTTERANCE`: only `message_type`.
333+
// Concatenating the finalized transcripts with `is_final` set to true,
334+
// the complete utterance becomes "to be or not to be that is the question".
323335
message StreamingRecognitionResult {
324336
// Type of the response message.
325337
enum MessageType {

0 commit comments

Comments
 (0)