feat(v3): add advanced settings for agent level (#137)

PiperOrigin-RevId: 387850898

Source-Link: googleapis/googleapis@05d477b

Source-Link: https://github.com/googleapis/googleapis-gen/commit/6982a6f5d3709f4e863918d3e09fa1c7d35163b7

feat(v3): add rollout config, state and failure reason for experiment
feat(v3): add insights export settings for security setting 
feat(v3): add language code for streaming recognition result and flow versions for query parameters
docs(v3): deprecate legacy logging settings

Author: gcf-owl-bot[bot]

google/cloud/dialogflowcx/__init__.py

@@ -71,6 +71,7 @@
     WebhooksAsyncClient,
 )
 
+from google.cloud.dialogflowcx_v3.types.advanced_settings import AdvancedSettings
 from google.cloud.dialogflowcx_v3.types.agent import Agent
 from google.cloud.dialogflowcx_v3.types.agent import AgentValidationResult
 from google.cloud.dialogflowcx_v3.types.agent import CreateAgentRequest
@@ -130,6 +131,8 @@
 from google.cloud.dialogflowcx_v3.types.experiment import GetExperimentRequest
 from google.cloud.dialogflowcx_v3.types.experiment import ListExperimentsRequest
 from google.cloud.dialogflowcx_v3.types.experiment import ListExperimentsResponse
+from google.cloud.dialogflowcx_v3.types.experiment import RolloutConfig
+from google.cloud.dialogflowcx_v3.types.experiment import RolloutState
 from google.cloud.dialogflowcx_v3.types.experiment import StartExperimentRequest
 from google.cloud.dialogflowcx_v3.types.experiment import StopExperimentRequest
 from google.cloud.dialogflowcx_v3.types.experiment import UpdateExperimentRequest
@@ -335,6 +338,7 @@
     "VersionsAsyncClient",
     "WebhooksClient",
     "WebhooksAsyncClient",
+    "AdvancedSettings",
     "Agent",
     "AgentValidationResult",
     "CreateAgentRequest",
@@ -386,6 +390,8 @@
     "GetExperimentRequest",
     "ListExperimentsRequest",
     "ListExperimentsResponse",
+    "RolloutConfig",
+    "RolloutState",
     "StartExperimentRequest",
     "StopExperimentRequest",
     "UpdateExperimentRequest",

google/cloud/dialogflowcx_v3/__init__.py

@@ -43,6 +43,7 @@
 from .services.webhooks import WebhooksClient
 from .services.webhooks import WebhooksAsyncClient
 
+from .types.advanced_settings import AdvancedSettings
 from .types.agent import Agent
 from .types.agent import AgentValidationResult
 from .types.agent import CreateAgentRequest
@@ -94,6 +95,8 @@
 from .types.experiment import GetExperimentRequest
 from .types.experiment import ListExperimentsRequest
 from .types.experiment import ListExperimentsResponse
+from .types.experiment import RolloutConfig
+from .types.experiment import RolloutState
 from .types.experiment import StartExperimentRequest
 from .types.experiment import StopExperimentRequest
 from .types.experiment import UpdateExperimentRequest
@@ -247,6 +250,7 @@
     "TransitionRouteGroupsAsyncClient",
     "VersionsAsyncClient",
     "WebhooksAsyncClient",
+    "AdvancedSettings",
     "Agent",
     "AgentValidationResult",
     "AgentsClient",
@@ -386,6 +390,8 @@
     "ResourceName",
     "ResponseMessage",
     "RestoreAgentRequest",
+    "RolloutConfig",
+    "RolloutState",
     "RunContinuousTestMetadata",
     "RunContinuousTestRequest",
     "RunContinuousTestResponse",

google/cloud/dialogflowcx_v3/services/agents/async_client.py

@@ -29,6 +29,7 @@
 from google.api_core import operation  # type: ignore
 from google.api_core import operation_async  # type: ignore
 from google.cloud.dialogflowcx_v3.services.agents import pagers
+from google.cloud.dialogflowcx_v3.types import advanced_settings
 from google.cloud.dialogflowcx_v3.types import agent
 from google.cloud.dialogflowcx_v3.types import agent as gcdc_agent
 from google.cloud.dialogflowcx_v3.types import flow

google/cloud/dialogflowcx_v3/services/agents/client.py

@@ -33,6 +33,7 @@
 from google.api_core import operation  # type: ignore
 from google.api_core import operation_async  # type: ignore
 from google.cloud.dialogflowcx_v3.services.agents import pagers
+from google.cloud.dialogflowcx_v3.types import advanced_settings
 from google.cloud.dialogflowcx_v3.types import agent
 from google.cloud.dialogflowcx_v3.types import agent as gcdc_agent
 from google.cloud.dialogflowcx_v3.types import flow

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

@@ -75,6 +75,8 @@ class SessionsAsyncClient:
     parse_transition_route_group_path = staticmethod(
         SessionsClient.parse_transition_route_group_path
     )
+    version_path = staticmethod(SessionsClient.version_path)
+    parse_version_path = staticmethod(SessionsClient.parse_version_path)
     webhook_path = staticmethod(SessionsClient.webhook_path)
     parse_webhook_path = staticmethod(SessionsClient.parse_webhook_path)
     common_billing_account_path = staticmethod(

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

@@ -296,6 +296,24 @@ def parse_transition_route_group_path(path: str) -> Dict[str, str]:
         )
         return m.groupdict() if m else {}
 
+    @staticmethod
+    def version_path(
+        project: str, location: str, agent: str, flow: str, version: str,
+    ) -> str:
+        """Returns a fully-qualified version string."""
+        return "projects/{project}/locations/{location}/agents/{agent}/flows/{flow}/versions/{version}".format(
+            project=project, location=location, agent=agent, flow=flow, version=version,
+        )
+
+    @staticmethod
+    def parse_version_path(path: str) -> Dict[str, str]:
+        """Parses a version path into its component segments."""
+        m = re.match(
+            r"^projects/(?P<project>.+?)/locations/(?P<location>.+?)/agents/(?P<agent>.+?)/flows/(?P<flow>.+?)/versions/(?P<version>.+?)$",
+            path,
+        )
+        return m.groupdict() if m else {}
+
     @staticmethod
     def webhook_path(project: str, location: str, agent: str, webhook: str,) -> str:
         """Returns a fully-qualified webhook string."""

google/cloud/dialogflowcx_v3/types/__init__.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+from .advanced_settings import AdvancedSettings
 from .agent import (
     Agent,
     AgentValidationResult,
@@ -73,6 +74,8 @@
     GetExperimentRequest,
     ListExperimentsRequest,
     ListExperimentsResponse,
+    RolloutConfig,
+    RolloutState,
     StartExperimentRequest,
     StopExperimentRequest,
     UpdateExperimentRequest,
@@ -235,6 +238,7 @@
 )
 
 __all__ = (
+    "AdvancedSettings",
     "Agent",
     "AgentValidationResult",
     "CreateAgentRequest",
@@ -286,6 +290,8 @@
     "GetExperimentRequest",
     "ListExperimentsRequest",
     "ListExperimentsResponse",
+    "RolloutConfig",
+    "RolloutState",
     "StartExperimentRequest",
     "StopExperimentRequest",
     "UpdateExperimentRequest",

google/cloud/dialogflowcx_v3/types/advanced_settings.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import proto  # type: ignore
+
+
+__protobuf__ = proto.module(
+    package="google.cloud.dialogflow.cx.v3", manifest={"AdvancedSettings",},
+)
+
+
+class AdvancedSettings(proto.Message):
+    r"""Hierarchical advanced settings for
+    agent/flow/page/fulfillment/parameter. Settings exposed at lower
+    level overrides the settings exposed at higher level.
+
+    Hierarchy: Agent->Flow->Page->Fulfillment/Parameter.
+
+    Attributes:
+        logging_settings (google.cloud.dialogflowcx_v3.types.AdvancedSettings.LoggingSettings):
+            Settings for logging.
+            Settings for Dialogflow History, Contact Center
+            messages, StackDriver logs, and speech logging.
+            Exposed at the following levels:
+            - Agent level.
+    """
+
+    class LoggingSettings(proto.Message):
+        r"""Define behaviors on logging.
+        Attributes:
+            enable_stackdriver_logging (bool):
+                If true, StackDriver logging is currently
+                enabled.
+            enable_interaction_logging (bool):
+                If true, DF Interaction logging is currently
+                enabled.
+        """
+
+        enable_stackdriver_logging = proto.Field(proto.BOOL, number=2,)
+        enable_interaction_logging = proto.Field(proto.BOOL, number=3,)
+
+    logging_settings = proto.Field(proto.MESSAGE, number=6, message=LoggingSettings,)
+
+
+__all__ = tuple(sorted(__protobuf__.manifest))

google/cloud/dialogflowcx_v3/types/agent.py

@@ -15,6 +15,9 @@
 #
 import proto  # type: ignore
 
+from google.cloud.dialogflowcx_v3.types import (
+    advanced_settings as gcdc_advanced_settings,
+)
 from google.cloud.dialogflowcx_v3.types import flow
 from google.protobuf import field_mask_pb2  # type: ignore
 
@@ -114,11 +117,18 @@ class Agent(proto.Message):
             reference for the agent. Format:
             ``projects/<Project ID>/locations/<Location ID>/securitySettings/<Security Settings ID>``.
         enable_stackdriver_logging (bool):
-            Indicates if stackdriver logging is enabled
-            for the agent.
+            Indicates if stackdriver logging is enabled for the agent.
+            Please use
+            [agent.advanced_settings][google.cloud.dialogflow.cx.v3.AdvancedSettings.LoggingSettings]
+            instead.
         enable_spell_correction (bool):
             Indicates if automatic spell correction is
             enabled in detect intent requests.
+        advanced_settings (google.cloud.dialogflowcx_v3.types.AdvancedSettings):
+            Hierarchical advanced settings for this
+            agent. The settings exposed at the lower level
+            overrides the settings exposed at the higher
+            level.
     """
 
     name = proto.Field(proto.STRING, number=1,)
@@ -135,6 +145,9 @@ class Agent(proto.Message):
     security_settings = proto.Field(proto.STRING, number=17,)
     enable_stackdriver_logging = proto.Field(proto.BOOL, number=18,)
     enable_spell_correction = proto.Field(proto.BOOL, number=20,)
+    advanced_settings = proto.Field(
+        proto.MESSAGE, number=22, message=gcdc_advanced_settings.AdvancedSettings,
+    )
 
 
 class ListAgentsRequest(proto.Message):

google/cloud/dialogflowcx_v3/types/experiment.py

@@ -26,6 +26,8 @@
         "Experiment",
         "VersionVariants",
         "VariantsHistory",
+        "RolloutConfig",
+        "RolloutState",
         "ListExperimentsRequest",
         "ListExperimentsResponse",
         "GetExperimentRequest",
@@ -57,12 +59,26 @@ class Experiment(proto.Message):
         state (google.cloud.dialogflowcx_v3.types.Experiment.State):
             The current state of the experiment.
             Transition triggered by
-            Expriments.StartExperiment: PENDING->RUNNING.
+            Experiments.StartExperiment: DRAFT->RUNNING.
             Transition triggered by
-            Expriments.CancelExperiment: PENDING->CANCELLED
-            or RUNNING->CANCELLED.
+            Experiments.CancelExperiment: DRAFT->DONE or
+            RUNNING->DONE.
         definition (google.cloud.dialogflowcx_v3.types.Experiment.Definition):
             The definition of the experiment.
+        rollout_config (google.cloud.dialogflowcx_v3.types.RolloutConfig):
+            The configuration for auto rollout. If set,
+            there should be exactly two variants in the
+            experiment (control variant being the default
+            version of the flow), the traffic allocation for
+            the non-control variant will gradually increase
+            to 100% when conditions are met, and eventually
+            replace the control variant to become the
+            default version of the flow.
+        rollout_state (google.cloud.dialogflowcx_v3.types.RolloutState):
+            State of the auto rollout process.
+        rollout_failure_reason (str):
+            The reason why rollout has failed. Should only be set when
+            state is ROLLOUT_FAILED.
         result (google.cloud.dialogflowcx_v3.types.Experiment.Result):
             Inference result of the experiment.
         create_time (google.protobuf.timestamp_pb2.Timestamp):
@@ -90,6 +106,7 @@ class State(proto.Enum):
         DRAFT = 1
         RUNNING = 2
         DONE = 3
+        ROLLOUT_FAILED = 4
 
     class Definition(proto.Message):
         r"""Definition of the experiment.
@@ -225,6 +242,9 @@ class VersionMetrics(proto.Message):
     description = proto.Field(proto.STRING, number=3,)
     state = proto.Field(proto.ENUM, number=4, enum=State,)
     definition = proto.Field(proto.MESSAGE, number=5, message=Definition,)
+    rollout_config = proto.Field(proto.MESSAGE, number=14, message="RolloutConfig",)
+    rollout_state = proto.Field(proto.MESSAGE, number=15, message="RolloutState",)
+    rollout_failure_reason = proto.Field(proto.STRING, number=16,)
     result = proto.Field(proto.MESSAGE, number=6, message=Result,)
     create_time = proto.Field(proto.MESSAGE, number=7, message=timestamp_pb2.Timestamp,)
     start_time = proto.Field(proto.MESSAGE, number=8, message=timestamp_pb2.Timestamp,)
@@ -283,6 +303,72 @@ class VariantsHistory(proto.Message):
     update_time = proto.Field(proto.MESSAGE, number=2, message=timestamp_pb2.Timestamp,)
 
 
+class RolloutConfig(proto.Message):
+    r"""The configuration for auto rollout.
+    Attributes:
+        rollout_steps (Sequence[google.cloud.dialogflowcx_v3.types.RolloutConfig.RolloutStep]):
+            Steps to roll out a flow version. Steps
+            should be sorted by percentage in ascending
+            order.
+        rollout_condition (str):
+            The conditions that are used to evaluate the success of a
+            rollout step. If not specified, all rollout steps will
+            proceed to the next one unless failure conditions are met.
+            E.g. "containment_rate > 60% AND callback_rate < 20%". See
+            the `conditions
+            reference <https://cloud.google.com/dialogflow/cx/docs/reference/condition>`__.
+        failure_condition (str):
+            The conditions that are used to evaluate the failure of a
+            rollout step. If not specified, no rollout steps will fail.
+            E.g. "containment_rate < 10% OR average_turn_count < 3". See
+            the `conditions
+            reference <https://cloud.google.com/dialogflow/cx/docs/reference/condition>`__.
+    """
+
+    class RolloutStep(proto.Message):
+        r"""A single rollout step with specified traffic allocation.
+        Attributes:
+            display_name (str):
+                The name of the rollout step;
+            traffic_percent (int):
+                The percentage of traffic allocated to the flow version of
+                this rollout step. (0%, 100%].
+            min_duration (google.protobuf.duration_pb2.Duration):
+                The minimum time that this step should last.
+                Should be longer than 1 hour. If not set, the
+                default minimum duration for each step will be 1
+                hour.
+        """
+
+        display_name = proto.Field(proto.STRING, number=1,)
+        traffic_percent = proto.Field(proto.INT32, number=2,)
+        min_duration = proto.Field(
+            proto.MESSAGE, number=3, message=duration_pb2.Duration,
+        )
+
+    rollout_steps = proto.RepeatedField(proto.MESSAGE, number=1, message=RolloutStep,)
+    rollout_condition = proto.Field(proto.STRING, number=2,)
+    failure_condition = proto.Field(proto.STRING, number=3,)
+
+
+class RolloutState(proto.Message):
+    r"""State of the auto-rollout process.
+    Attributes:
+        step (str):
+            Display name of the current auto rollout
+            step.
+        step_index (int):
+            Index of the current step in the auto rollout
+            steps list.
+        start_time (google.protobuf.timestamp_pb2.Timestamp):
+            Start time of the current step.
+    """
+
+    step = proto.Field(proto.STRING, number=1,)
+    step_index = proto.Field(proto.INT32, number=3,)
+    start_time = proto.Field(proto.MESSAGE, number=2, message=timestamp_pb2.Timestamp,)
+
+
 class ListExperimentsRequest(proto.Message):
     r"""The request message for
     [Experiments.ListExperiments][google.cloud.dialogflow.cx.v3.Experiments.ListExperiments].