docs(v3beta1): added explanation for uri fields in resources (#273)

- [ ] Regenerate this pull request now.

docs(v3beta1): improved docs format

PiperOrigin-RevId: 435479428

Source-Link: googleapis/googleapis@4dd75c2

Source-Link: googleapis/googleapis-gen@0f3e9df
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMGYzZTlkZjM4OGIyZjg0YTNkNjgxMjgyNmQyMGE5NTA0NDdjNmViYiJ9

google/cloud/dialogflowcx_v3beta1/services/sessions/async_client.py

@@ -380,32 +380,31 @@ def request_generator():
                 method.
                 Multiple request messages should be sent in order:
 
-                1.  The first message must contain
+                1. The first message must contain
                 [session][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.session],
                 [query_input][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_input]
                 plus optionally
                 [query_params][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_params].
-                If the client     wants to receive an audio response, it
+                If the client wants to receive an audio response, it
                 should also contain
                 [output_audio_config][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.output_audio_config].
                 2.  If
                 [query_input][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_input]
                 was set to
                 [query_input.audio.config][google.cloud.dialogflow.cx.v3beta1.AudioInput.config],
-                all subsequent messages     must contain
+                all subsequent messages must contain
                 [query_input.audio.audio][google.cloud.dialogflow.cx.v3beta1.AudioInput.audio]
-                to continue with     Speech recognition.
-                    If you decide to rather detect an intent from text
+                to continue with Speech recognition.
+                If you decide to rather detect an intent from text
                 input after you already started Speech recognition,
-                please send a message     with
+                please send a message with
                 [query_input.text][google.cloud.dialogflow.cx.v3beta1.QueryInput.text].
-                    However, note that:
-
-                    * Dialogflow will bill you for the audio duration so
-                far.     * Dialogflow discards all Speech recognition
-                results in favor of the       input text.
-                    * Dialogflow will use the language code from the
-                first message.
+                However, note that:
+                * Dialogflow will bill you for the audio duration so
+                far. * Dialogflow discards all Speech recognition
+                results in favor of the input text.
+                * Dialogflow will use the language code from the first
+                message.
                 After you sent all input, you must half-close or abort
                 the request stream.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,

google/cloud/dialogflowcx_v3beta1/services/sessions/client.py

@@ -689,32 +689,31 @@ def request_generator():
                 method.
                 Multiple request messages should be sent in order:
 
-                1.  The first message must contain
+                1. The first message must contain
                 [session][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.session],
                 [query_input][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_input]
                 plus optionally
                 [query_params][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_params].
-                If the client     wants to receive an audio response, it
+                If the client wants to receive an audio response, it
                 should also contain
                 [output_audio_config][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.output_audio_config].
                 2.  If
                 [query_input][google.cloud.dialogflow.cx.v3beta1.StreamingDetectIntentRequest.query_input]
                 was set to
                 [query_input.audio.config][google.cloud.dialogflow.cx.v3beta1.AudioInput.config],
-                all subsequent messages     must contain
+                all subsequent messages must contain
                 [query_input.audio.audio][google.cloud.dialogflow.cx.v3beta1.AudioInput.audio]
-                to continue with     Speech recognition.
-                    If you decide to rather detect an intent from text
+                to continue with Speech recognition.
+                If you decide to rather detect an intent from text
                 input after you already started Speech recognition,
-                please send a message     with
+                please send a message with
                 [query_input.text][google.cloud.dialogflow.cx.v3beta1.QueryInput.text].
-                    However, note that:
-
-                    * Dialogflow will bill you for the audio duration so
-                far.     * Dialogflow discards all Speech recognition
-                results in favor of the       input text.
-                    * Dialogflow will use the language code from the
-                first message.
+                However, note that:
+                * Dialogflow will bill you for the audio duration so
+                far. * Dialogflow discards all Speech recognition
+                results in favor of the input text.
+                * Dialogflow will use the language code from the first
+                message.
                 After you sent all input, you must half-close or abort
                 the request stream.
             retry (google.api_core.retry.Retry): Designation of what errors, if any,

google/cloud/dialogflowcx_v3beta1/types/agent.py

@@ -269,6 +269,12 @@ class ExportAgentRequest(proto.Message):
             export the agent to. The format of this URI must be
             ``gs://<bucket-name>/<object-name>``. If left unspecified,
             the serialized agent is returned inline.
+
+            Dialogflow performs a write operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have write permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
         environment (str):
             Optional. Environment name. If not set, draft environment is
             assumed. Format:
@@ -329,6 +335,12 @@ class RestoreAgentRequest(proto.Message):
             restore agent from. The format of this URI must be
             ``gs://<bucket-name>/<object-name>``.
 
+            Dialogflow performs a read operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have read permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
+
             This field is a member of `oneof`_ ``agent``.
         agent_content (bytes):
             Uncompressed raw byte content for agent.

google/cloud/dialogflowcx_v3beta1/types/flow.py

@@ -437,6 +437,12 @@ class ImportFlowRequest(proto.Message):
             import flow from. The format of this URI must be
             ``gs://<bucket-name>/<object-name>``.
 
+            Dialogflow performs a read operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have read permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
+
             This field is a member of `oneof`_ ``flow``.
         flow_content (bytes):
             Uncompressed raw byte content for flow.
@@ -485,6 +491,12 @@ class ExportFlowRequest(proto.Message):
             export the flow to. The format of this URI must be
             ``gs://<bucket-name>/<object-name>``. If left unspecified,
             the serialized flow is returned inline.
+
+            Dialogflow performs a write operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have write permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
         include_referenced_flows (bool):
             Optional. Whether to export flows referenced
             by the specified flow.

google/cloud/dialogflowcx_v3beta1/types/session.py

@@ -170,12 +170,12 @@ class StreamingDetectIntentRequest(proto.Message):
        recognition, please send a message with
        [query_input.text][google.cloud.dialogflow.cx.v3beta1.QueryInput.text].
 
-       However, note that:
+    However, note that:
 
-       -  Dialogflow will bill you for the audio duration so far.
-       -  Dialogflow discards all Speech recognition results in favor of
-          the input text.
-       -  Dialogflow will use the language code from the first message.
+    -  Dialogflow will bill you for the audio duration so far.
+    -  Dialogflow discards all Speech recognition results in favor of
+       the input text.
+    -  Dialogflow will use the language code from the first message.
 
     After you sent all input, you must half-close or abort the request
     stream.
@@ -435,18 +435,13 @@ class QueryParameters(proto.Message):
 
             -  MapKey type: string
             -  MapKey value: parameter name
-            -  MapValue type:
-
-               -  If parameter's entity type is a composite entity: map
-               -  Else: depending on parameter value type, could be one
-                  of string, number, boolean, null, list or map
-
-            -  MapValue value:
-
-               -  If parameter's entity type is a composite entity: map
-                  from composite entity property names to property
-                  values
-               -  Else: parameter value
+            -  MapValue type: If parameter's entity type is a composite
+               entity then use map, otherwise, depending on the
+               parameter value type, it could be one of string, number,
+               boolean, null, list or map.
+            -  MapValue value: If parameter's entity type is a composite
+               entity then use map from composite entity property names
+               to property values, otherwise, use parameter value.
         current_page (str):
             The unique identifier of the
             [page][google.cloud.dialogflow.cx.v3beta1.Page] to override
@@ -622,18 +617,13 @@ class QueryResult(proto.Message):
 
             -  MapKey type: string
             -  MapKey value: parameter name
-            -  MapValue type:
-
-               -  If parameter's entity type is a composite entity: map
-               -  Else: depending on parameter value type, could be one
-                  of string, number, boolean, null, list or map
-
-            -  MapValue value:
-
-               -  If parameter's entity type is a composite entity: map
-                  from composite entity property names to property
-                  values
-               -  Else: parameter value
+            -  MapValue type: If parameter's entity type is a composite
+               entity then use map, otherwise, depending on the
+               parameter value type, it could be one of string, number,
+               boolean, null, list or map.
+            -  MapValue value: If parameter's entity type is a composite
+               entity then use map from composite entity property names
+               to property values, otherwise, use parameter value.
         response_messages (Sequence[google.cloud.dialogflowcx_v3beta1.types.ResponseMessage]):
             The list of rich messages returned to the
             client. Responses vary from simple text messages
@@ -807,25 +797,22 @@ class Match(proto.Message):
             [``NO_INPUT``][google.cloud.dialogflow.cx.v3beta1.Match.MatchType]
             match types.
         parameters (google.protobuf.struct_pb2.Struct):
-            The collection of parameters extracted from
-            the query.
-            Depending on your protocol or client library
-            language, this is a map, associative array,
-            symbol table, dictionary, or JSON object
-            composed of a collection of (MapKey, MapValue)
+            The collection of parameters extracted from the query.
+
+            Depending on your protocol or client library language, this
+            is a map, associative array, symbol table, dictionary, or
+            JSON object composed of a collection of (MapKey, MapValue)
             pairs:
-            -   MapKey type: string
-            -   MapKey value: parameter name
-            -   MapValue type:
-                -   If parameter's entity type is a
-            composite entity: map     -   Else: depending on
-            parameter value type, could be one of string,
-            number, boolean, null, list or map
-            -   MapValue value:
-                -   If parameter's entity type is a
-            composite entity:         map from composite
-            entity property names to property values     -
-            Else: parameter value
+
+            -  MapKey type: string
+            -  MapKey value: parameter name
+            -  MapValue type: If parameter's entity type is a composite
+               entity then use map, otherwise, depending on the
+               parameter value type, it could be one of string, number,
+               boolean, null, list or map.
+            -  MapValue value: If parameter's entity type is a composite
+               entity then use map from composite entity property names
+               to property values, otherwise, use parameter value.
         resolved_input (str):
             Final text input which was matched during
             MatchIntent. This value can be different from

google/cloud/dialogflowcx_v3beta1/types/test_case.py

@@ -818,6 +818,12 @@ class ImportTestCasesRequest(proto.Message):
             import test cases from. The format of this URI must be
             ``gs://<bucket-name>/<object-name>``.
 
+            Dialogflow performs a read operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have read permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
+
             This field is a member of `oneof`_ ``source``.
         content (bytes):
             Uncompressed raw byte content for test cases.
@@ -888,6 +894,12 @@ class ExportTestCasesRequest(proto.Message):
             ``gs://<bucket-name>/<object-name>``. If unspecified, the
             serialized test cases is returned inline.
 
+            Dialogflow performs a write operation for the Cloud Storage
+            object on the caller's behalf, so your request
+            authentication must have write permissions for the object.
+            For more information, see `Dialogflow access
+            control <https://cloud.google.com/dialogflow/cx/docs/concept/access-control#storage>`__.
+
             This field is a member of `oneof`_ ``destination``.
         data_format (google.cloud.dialogflowcx_v3beta1.types.ExportTestCasesRequest.DataFormat):
             The data format of the exported test cases. If not

google/cloud/dialogflowcx_v3beta1/types/webhook.py

@@ -99,22 +99,20 @@ class GenericWebService(proto.Message):
                 The HTTP request headers to send together
                 with webhook requests.
             allowed_ca_certs (Sequence[bytes]):
-                Optional. Specifies a list of allowed custom
-                CA certificates (in DER format) for HTTPS
-                verification. This overrides the default SSL
-                trust store. If this is empty or unspecified,
-                Dialogflow will use Google's default trust store
-                to verify certificates.
-                N.B. Make sure the HTTPS server certificates are
-                signed with "subject alt name". For instance a
-                certificate can be self-signed using the
-                following command,
-                   openssl x509 -req -days 200 -in
-                example.com.csr \      -signkey example.com.key
-                \
-                     -out example.com.crt \
-                     -extfile <(printf
-                "\nsubjectAltName='DNS:www.example.com'")
+                Optional. Specifies a list of allowed custom CA certificates
+                (in DER format) for HTTPS verification. This overrides the
+                default SSL trust store. If this is empty or unspecified,
+                Dialogflow will use Google's default trust store to verify
+                certificates. N.B. Make sure the HTTPS server certificates
+                are signed with "subject alt name". For instance a
+                certificate can be self-signed using the following command,
+
+                ::
+
+                      openssl x509 -req -days 200 -in example.com.csr \
+                        -signkey example.com.key \
+                        -out example.com.crt \
+                        -extfile <(printf "\nsubjectAltName='DNS:www.example.com'")
         """
 
         uri = proto.Field(proto.STRING, number=1,)