feat: added API for changelogs docs: clarified semantic of the streaming APIs

.github/.OwlBot.lock.yaml

@@ -1,3 +1,3 @@
 docker:
   image: gcr.io/cloud-devrel-public-resources/owlbot-nodejs:latest
-  digest: sha256:bbb8dd6576ac58830a07fc17e9511ae898be44f2219d3344449b125df9854441
+  digest: sha256:c5576a2a649af7ea4f1100e691a44584980e298277467460852c53642354cb80

protos/google/cloud/dialogflow/cx/v3/audio_config.proto

@@ -31,6 +31,31 @@ option java_package = "com.google.cloud.dialogflow.cx.v3";
 option objc_class_prefix = "DF";
 option ruby_package = "Google::Cloud::Dialogflow::CX::V3";
 
+// Information for a word recognized by the speech recognizer.
+message SpeechWordInfo {
+  // The word this info is for.
+  string word = 3;
+
+  // Time offset relative to the beginning of the audio that corresponds to the
+  // start of the spoken word. This is an experimental feature and the accuracy
+  // of the time offset can vary.
+  google.protobuf.Duration start_offset = 1;
+
+  // Time offset relative to the beginning of the audio that corresponds to the
+  // end of the spoken word. This is an experimental feature and the accuracy of
+  // the time offset can vary.
+  google.protobuf.Duration end_offset = 2;
+
+  // The Speech confidence between 0.0 and 1.0 for this word. A higher number
+  // indicates an estimated greater likelihood that the recognized word is
+  // correct. The default of 0.0 is a sentinel value indicating that confidence
+  // was not set.
+  //
+  // This field is not guaranteed to be fully stable over time for the same
+  // audio input. Users should also not rely on it to always be provided.
+  float confidence = 4;
+}
+
 // Audio encoding of the audio content sent in the conversational query request.
 // Refer to the
 // [Cloud Speech API
@@ -80,31 +105,6 @@ enum AudioEncoding {
   AUDIO_ENCODING_SPEEX_WITH_HEADER_BYTE = 7;
 }
 
-// Information for a word recognized by the speech recognizer.
-message SpeechWordInfo {
-  // The word this info is for.
-  string word = 3;
-
-  // Time offset relative to the beginning of the audio that corresponds to the
-  // start of the spoken word. This is an experimental feature and the accuracy
-  // of the time offset can vary.
-  google.protobuf.Duration start_offset = 1;
-
-  // Time offset relative to the beginning of the audio that corresponds to the
-  // end of the spoken word. This is an experimental feature and the accuracy of
-  // the time offset can vary.
-  google.protobuf.Duration end_offset = 2;
-
-  // The Speech confidence between 0.0 and 1.0 for this word. A higher number
-  // indicates an estimated greater likelihood that the recognized word is
-  // correct. The default of 0.0 is a sentinel value indicating that confidence
-  // was not set.
-  //
-  // This field is not guaranteed to be fully stable over time for the same
-  // audio input. Users should also not rely on it to always be provided.
-  float confidence = 4;
-}
-
 // Instructs the speech recognizer on how to process the audio content.
 message InputAudioConfig {
   // Required. Audio encoding of the audio content to process.

protos/google/cloud/dialogflow/cx/v3/security_settings.proto

@@ -245,6 +245,11 @@ message SecuritySettings {
   // [DLP](https://cloud.google.com/dlp/docs) inspect template name. Use this
   // template to define inspect base settings.
   //
+  // The `DLP Inspect Templates Reader` role is needed on the Dialogflow
+  // service identity service account (has the form
+  // `service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com`)
+  // for your agent's project.
+  //
   // If empty, we use the default DLP inspect config.
   //
   // The template name will have one of the following formats:
@@ -261,6 +266,11 @@ message SecuritySettings {
   // [DLP](https://cloud.google.com/dlp/docs) deidentify template name. Use this
   // template to define de-identification configuration for the content.
   //
+  // The `DLP De-identify Templates Reader` role is needed on the Dialogflow
+  // service identity service account (has the form
+  // `service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com`)
+  // for your agent's project.
+  //
   // If empty, Dialogflow replaces sensitive info with `[redacted]` text.
   //
   // The template name will have one of the following formats:
@@ -281,7 +291,7 @@ message SecuritySettings {
     // Retains data in interaction logging for the specified number of days.
     // This does not apply to Cloud logging, which is owned by the user - not
     // Dialogflow.
-    // User must Set a value lower than Dialogflow's default 30d TTL. Setting a
+    // User must set a value lower than Dialogflow's default 365d TTL. Setting a
     // value higher than that has no effect.
     // A missing value or setting to 0 also means we use Dialogflow's default
     // TTL.

protos/google/cloud/dialogflow/cx/v3/version.proto

@@ -47,7 +47,8 @@ service Versions {
       "https://www.googleapis.com/auth/cloud-platform,"
       "https://www.googleapis.com/auth/dialogflow";
 
-  // Returns the list of all versions in the specified [Flow][google.cloud.dialogflow.cx.v3.Flow].
+  // Returns the list of all versions in the specified
+  // [Flow][google.cloud.dialogflow.cx.v3.Flow].
   rpc ListVersions(ListVersionsRequest) returns (ListVersionsResponse) {
     option (google.api.http) = {
       get: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/versions"
@@ -63,15 +64,18 @@ service Versions {
     option (google.api.method_signature) = "name";
   }
 
-  // Creates a [Version][google.cloud.dialogflow.cx.v3.Version] in the specified [Flow][google.cloud.dialogflow.cx.v3.Flow].
+  // Creates a [Version][google.cloud.dialogflow.cx.v3.Version] in the specified
+  // [Flow][google.cloud.dialogflow.cx.v3.Flow].
   //
   // This method is a [long-running
   // operation](https://cloud.google.com/dialogflow/cx/docs/how/long-running-operation).
   // The returned `Operation` type has the following method-specific fields:
   //
-  // - `metadata`: [CreateVersionOperationMetadata][google.cloud.dialogflow.cx.v3.CreateVersionOperationMetadata]
+  // - `metadata`:
+  // [CreateVersionOperationMetadata][google.cloud.dialogflow.cx.v3.CreateVersionOperationMetadata]
   // - `response`: [Version][google.cloud.dialogflow.cx.v3.Version]
-  rpc CreateVersion(CreateVersionRequest) returns (google.longrunning.Operation) {
+  rpc CreateVersion(CreateVersionRequest)
+      returns (google.longrunning.Operation) {
     option (google.api.http) = {
       post: "/v3/{parent=projects/*/locations/*/agents/*/flows/*}/versions"
       body: "version"
@@ -121,17 +125,27 @@ service Versions {
       metadata_type: "google.protobuf.Struct"
     };
   }
+
+  // Compares the specified base version with target version.
+  rpc CompareVersions(CompareVersionsRequest)
+      returns (CompareVersionsResponse) {
+    option (google.api.http) = {
+      post: "/v3/{base_version=projects/*/locations/*/agents/*/flows/*/versions/*}:compareVersions"
+      body: "*"
+    };
+    option (google.api.method_signature) = "base_version";
+  }
 }
 
 // Metadata associated with the long running operation for
 // [Versions.CreateVersion][google.cloud.dialogflow.cx.v3.Versions.CreateVersion].
 message CreateVersionOperationMetadata {
   // Name of the created version.
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>/versions/<Version ID>`.
+  // Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
   string version = 1 [(google.api.resource_reference) = {
-                        type: "dialogflow.googleapis.com/Version"
-                      }];
+    type: "dialogflow.googleapis.com/Version"
+  }];
 }
 
 // Represents a version of a flow.
@@ -156,9 +170,10 @@ message Version {
     FAILED = 3;
   }
 
-  // Format: projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>/versions/<Version ID>. Version ID is a self-increasing
-  // number generated by Dialogflow upon version creation.
+  // Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
+  // Version ID is a self-increasing number generated by Dialogflow upon version
+  // creation.
   string name = 1;
 
   // Required. The human-readable name of the version. Limit of 64 characters.
@@ -172,18 +187,20 @@ message Version {
   NluSettings nlu_settings = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Create time of the version.
-  google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+  google.protobuf.Timestamp create_time = 5
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The state of this version. This field is read-only and cannot be set by
-  // create and update methods.
+  // Output only. The state of this version. This field is read-only and cannot
+  // be set by create and update methods.
   State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
-// The request message for [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions].
+// The request message for
+// [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions].
 message ListVersionsRequest {
-  // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to list all versions for.
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>`.
+  // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to list all
+  // versions for. Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -199,7 +216,8 @@ message ListVersionsRequest {
   string page_token = 3;
 }
 
-// The response message for [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions].
+// The response message for
+// [Versions.ListVersions][google.cloud.dialogflow.cx.v3.Versions.ListVersions].
 message ListVersionsResponse {
   // A list of versions. There will be a maximum number of items returned based
   // on the page_size field in the request. The list may in some cases be empty
@@ -211,11 +229,12 @@ message ListVersionsResponse {
   string next_page_token = 2;
 }
 
-// The request message for [Versions.GetVersion][google.cloud.dialogflow.cx.v3.Versions.GetVersion].
+// The request message for
+// [Versions.GetVersion][google.cloud.dialogflow.cx.v3.Versions.GetVersion].
 message GetVersionRequest {
   // Required. The name of the [Version][google.cloud.dialogflow.cx.v3.Version].
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>/versions/<Version ID>`.
+  // Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -224,11 +243,12 @@ message GetVersionRequest {
   ];
 }
 
-// The request message for [Versions.CreateVersion][google.cloud.dialogflow.cx.v3.Versions.CreateVersion].
+// The request message for
+// [Versions.CreateVersion][google.cloud.dialogflow.cx.v3.Versions.CreateVersion].
 message CreateVersionRequest {
-  // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to create an [Version][google.cloud.dialogflow.cx.v3.Version] for.
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>`.
+  // Required. The [Flow][google.cloud.dialogflow.cx.v3.Flow] to create an
+  // [Version][google.cloud.dialogflow.cx.v3.Version] for. Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -240,21 +260,24 @@ message CreateVersionRequest {
   Version version = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
-// The request message for [Versions.UpdateVersion][google.cloud.dialogflow.cx.v3.Versions.UpdateVersion].
+// The request message for
+// [Versions.UpdateVersion][google.cloud.dialogflow.cx.v3.Versions.UpdateVersion].
 message UpdateVersionRequest {
   // Required. The version to update.
   Version version = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // Required. The mask to control which fields get updated. Currently only `description`
-  // and `display_name` can be updated.
-  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
+  // Required. The mask to control which fields get updated. Currently only
+  // `description` and `display_name` can be updated.
+  google.protobuf.FieldMask update_mask = 2
+      [(google.api.field_behavior) = REQUIRED];
 }
 
-// The request message for [Versions.DeleteVersion][google.cloud.dialogflow.cx.v3.Versions.DeleteVersion].
+// The request message for
+// [Versions.DeleteVersion][google.cloud.dialogflow.cx.v3.Versions.DeleteVersion].
 message DeleteVersionRequest {
-  // Required. The name of the [Version][google.cloud.dialogflow.cx.v3.Version] to delete.
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>/versions/<Version ID>`.
+  // Required. The name of the [Version][google.cloud.dialogflow.cx.v3.Version]
+  // to delete. Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -263,11 +286,12 @@ message DeleteVersionRequest {
   ];
 }
 
-// The request message for [Versions.LoadVersion][google.cloud.dialogflow.cx.v3.Versions.LoadVersion].
+// The request message for
+// [Versions.LoadVersion][google.cloud.dialogflow.cx.v3.Versions.LoadVersion].
 message LoadVersionRequest {
-  // Required. The [Version][google.cloud.dialogflow.cx.v3.Version] to be loaded to draft flow.
-  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
-  // ID>/flows/<Flow ID>/versions/<Version ID>`.
+  // Required. The [Version][google.cloud.dialogflow.cx.v3.Version] to be loaded
+  // to draft flow. Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -281,3 +305,52 @@ message LoadVersionRequest {
   // will not be overridden (i.e. intents, entities, webhooks).
   bool allow_override_agent_resources = 2;
 }
+
+// The request message for
+// [Versions.CompareVersions][google.cloud.dialogflow.cx.v3.Versions.CompareVersions].
+message CompareVersionsRequest {
+  // Required. Name of the base flow version to compare with the target version.
+  // Use version ID `0` to indicate the draft version of the specified flow.
+  //
+  // Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
+  string base_version = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/Version"
+    }
+  ];
+
+  // Required. Name of the target flow version to compare with the
+  // base version. Use version ID `0` to indicate the draft version of the
+  // specified flow. Format:
+  // `projects/<ProjectID>/locations/<LocationID>/agents/<AgentID>/flows/<FlowID>/versions/<VersionID>`.
+  string target_version = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "dialogflow.googleapis.com/Version"
+    }
+  ];
+
+  // The language to compare the flow versions for.
+  //
+  // If not specified, the agent's default language is used.
+  // [Many
+  // languages](https://cloud.google.com/dialogflow/docs/reference/language) are
+  // supported. Note: languages must be enabled in the agent before they can be
+  // used.
+  string language_code = 3;
+}
+
+// The response message for
+// [Versions.CompareVersions][google.cloud.dialogflow.cx.v3.Versions.CompareVersions].
+message CompareVersionsResponse {
+  // JSON representation of the base version content.
+  string base_version_content_json = 1;
+
+  // JSON representation of the target version content.
+  string target_version_content_json = 2;
+
+  // The timestamp when the two version compares.
+  google.protobuf.Timestamp compare_time = 3;
+}