# Discovery Engine API . projects . locations . collections . engines . controls

## Instance Methods

Close httplib2 connections.

Creates a Control. By default 1000 controls are allowed for a data store. A request can be submitted to adjust this limit. If the Control to create already exists, an ALREADY_EXISTS error is returned.

Deletes a Control. If the Control to delete does not exist, a NOT_FOUND error is returned.

Gets a Control.

Lists all Controls by their parent DataStore.

Retrieves the next page of results.

Updates a Control. Control action type cannot be changed. If the Control to update does not exist, a NOT_FOUND error is returned.

### Method Details

`close()`

    Close httplib2 connections.

`create(parent, body=None, controlId=None, x__xgafv=None)`

    Creates a Control. By default 1000 controls are allowed for a data store. A request can be submitted to adjust this limit. If the Control to create already exists, an ALREADY_EXISTS error is returned.

    Args:
      parent: string, Required. Full resource name of parent data store. Format: `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}` or `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}`. (required)
      body: object, The request body.
        The object takes the form of:

    { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
      "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
        "A String",
      ],
      "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
        "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
        "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
          "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
          "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
            { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
              "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
              "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
            },
          ],
          "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
          "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
        },
      },
      "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
        { # Defines circumstances to be checked before allowing a behavior
          "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
            { # Used for time-dependent conditions.
              "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
              "startTime": "A String", # Start of time range. Range is inclusive.
            },
          ],
          "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
          "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
            { # Matcher for search request query
              "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
              "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
            },
          ],
        },
      ],
      "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
      "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
        "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
      "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
        "dataStore": "A String", # Required. Data store with which this promotion is attached to.
        "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
          "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
          "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
          "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
          "imageUri": "A String", # Optional. The promotion thumbnail image url.
          "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
          "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
        },
      },
      "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
        "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
      "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
        "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
          "A String",
        ],
      },
      "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
        "A String",
      ],
    }

      controlId: string, Required. The ID to use for the Control, which will become the final component of the Control's resource name. This value must be within 1-63 characters. Valid characters are /a-z-_/.
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
      "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
        "A String",
      ],
      "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
        "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
        "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
          "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
          "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
            { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
              "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
              "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
            },
          ],
          "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
          "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
        },
      },
      "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
        { # Defines circumstances to be checked before allowing a behavior
          "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
            { # Used for time-dependent conditions.
              "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
              "startTime": "A String", # Start of time range. Range is inclusive.
            },
          ],
          "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
          "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
            { # Matcher for search request query
              "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
              "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
            },
          ],
        },
      ],
      "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
      "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
        "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
      "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
        "dataStore": "A String", # Required. Data store with which this promotion is attached to.
        "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
          "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
          "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
          "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
          "imageUri": "A String", # Optional. The promotion thumbnail image url.
          "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
          "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
        },
      },
      "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
        "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
      "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
        "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
          "A String",
        ],
      },
      "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
        "A String",
      ],
    }

`delete(name, x__xgafv=None)`

    Deletes a Control. If the Control to delete does not exist, a NOT_FOUND error is returned.

    Args:
      name: string, Required. The resource name of the Control to delete. Format: `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}/controls/{control_id}` (required)
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # A generic empty message that you can re-use to avoid defining duplicated empty messages in your APIs. A typical example is to use it as the request or the response type of an API method. For instance: service Foo { rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); }
    }

`get(name, x__xgafv=None)`

    Gets a Control.

    Args:
      name: string, Required. The resource name of the Control to get. Format: `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}/controls/{control_id}` (required)
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
      "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
        "A String",
      ],
      "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
        "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
        "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
          "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
          "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
            { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
              "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
              "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
            },
          ],
          "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
          "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
        },
      },
      "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
        { # Defines circumstances to be checked before allowing a behavior
          "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
            { # Used for time-dependent conditions.
              "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
              "startTime": "A String", # Start of time range. Range is inclusive.
            },
          ],
          "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
          "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
            { # Matcher for search request query
              "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
              "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
            },
          ],
        },
      ],
      "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
      "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
        "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
      "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
        "dataStore": "A String", # Required. Data store with which this promotion is attached to.
        "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
          "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
          "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
          "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
          "imageUri": "A String", # Optional. The promotion thumbnail image url.
          "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
          "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
        },
      },
      "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
        "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
      "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
        "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
          "A String",
        ],
      },
      "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
        "A String",
      ],
    }

`list(parent, filter=None, pageSize=None, pageToken=None, x__xgafv=None)`

    Lists all Controls by their parent DataStore.

    Args:
      parent: string, Required. The data store resource name. Format: `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}` or `projects/{project}/locations/{location}/collections/{collection_id}/engines/{engine_id}`. (required)
      filter: string, Optional. A filter to apply on the list results. Supported features: * List all the products under the parent branch if filter is unset. Currently this field is unsupported.
      pageSize: integer, Optional. Maximum number of results to return. If unspecified, defaults to 50. Max allowed value is 1000.
      pageToken: string, Optional. A page token, received from a previous `ListControls` call. Provide this to retrieve the subsequent page.
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Response for ListControls method.
      "controls": [ # All the Controls for a given data store.
        { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
          "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
            "A String",
          ],
          "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
            "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
            "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
            "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
            "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
            "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
              "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
              "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
                { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
                  "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
                  "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
                },
              ],
              "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
              "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
            },
          },
          "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
            { # Defines circumstances to be checked before allowing a behavior
              "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
                { # Used for time-dependent conditions.
                  "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
                  "startTime": "A String", # Start of time range. Range is inclusive.
                },
              ],
              "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
              "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
                { # Matcher for search request query
                  "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
                  "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
                },
              ],
            },
          ],
          "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
          "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
            "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
            "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
          },
          "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
          "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
            "dataStore": "A String", # Required. Data store with which this promotion is attached to.
            "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
              "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
              "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
              "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
              "imageUri": "A String", # Optional. The promotion thumbnail image url.
              "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
              "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
            },
          },
          "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
            "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
          },
          "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
          "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
            "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
              "A String",
            ],
          },
          "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
            "A String",
          ],
        },
      ],
      "nextPageToken": "A String", # Pagination token, if not returned indicates the last page.
    }

`list_next()`

    Retrieves the next page of results.

            Args:
              previous_request: The request for the previous page. (required)
              previous_response: The response from the request for the previous page. (required)

            Returns:
              A request object that you can call 'execute()' on to request the next
              page. Returns None if there are no more items in the collection.

`patch(name, body=None, updateMask=None, x__xgafv=None)`

    Updates a Control. Control action type cannot be changed. If the Control to update does not exist, a NOT_FOUND error is returned.

    Args:
      name: string, Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*` (required)
      body: object, The request body.
        The object takes the form of:

    { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
      "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
        "A String",
      ],
      "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
        "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
        "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
          "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
          "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
            { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
              "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
              "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
            },
          ],
          "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
          "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
        },
      },
      "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
        { # Defines circumstances to be checked before allowing a behavior
          "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
            { # Used for time-dependent conditions.
              "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
              "startTime": "A String", # Start of time range. Range is inclusive.
            },
          ],
          "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
          "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
            { # Matcher for search request query
              "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
              "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
            },
          ],
        },
      ],
      "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
      "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
        "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
      "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
        "dataStore": "A String", # Required. Data store with which this promotion is attached to.
        "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
          "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
          "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
          "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
          "imageUri": "A String", # Optional. The promotion thumbnail image url.
          "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
          "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
        },
      },
      "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
        "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
      "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
        "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
          "A String",
        ],
      },
      "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
        "A String",
      ],
    }

      updateMask: string, Optional. Indicates which fields in the provided Control to update. The following are NOT supported: * Control.name * Control.solution_type If not set or empty, all supported fields are updated.
      x__xgafv: string, V1 error format.
        Allowed values
          1 - v1 error format
          2 - v2 error format

    Returns:
      An object of the form:

        { # Defines a conditioned behavior to employ during serving. Must be attached to a ServingConfig to be considered at serving time. Permitted actions dependent on `SolutionType`.
      "associatedServingConfigIds": [ # Output only. List of all ServingConfig IDs this control is attached to. May take up to 10 minutes to update after changes.
        "A String",
      ],
      "boostAction": { # Adjusts order of products in returned list. # Defines a boost-type control
        "boost": 3.14, # Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "dataStore": "A String", # Required. Specifies which data store's documents can be boosted by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. Specifies which products to apply the boost to. If no filter is provided all products will be boosted (No-op). Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
        "fixedBoost": 3.14, # Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0 (No-op).
        "interpolationBoostSpec": { # Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above. # Optional. Complex specification for custom ranking based on customer defined attribute value.
          "attributeType": "A String", # Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified field_name. In the case of numerical it is straightforward i.e. attribute_value = numerical_field_value. In the case of freshness however, attribute_value = (time.now() - datetime_field_value).
          "controlPoints": [ # Optional. The control points used to define the curve. The monotonic function (defined through the interpolation_type above) passes through the control points listed here.
            { # The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).
              "attributeValue": "A String", # Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD `dayTimeDuration` value (a restricted subset of an ISO 8601 duration value). The pattern for this is: `nDnM]`.
              "boostAmount": 3.14, # Optional. The value between -1 to 1 by which to boost the score if the attribute_value evaluates to the value specified above.
            },
          ],
          "fieldName": "A String", # Optional. The name of the field whose value will be used to determine the boost amount.
          "interpolationType": "A String", # Optional. The interpolation type to be applied to connect the control points listed below.
        },
      },
      "conditions": [ # Determines when the associated action will trigger. Omit to always apply the action. Currently only a single condition may be specified. Otherwise an INVALID ARGUMENT error is thrown.
        { # Defines circumstances to be checked before allowing a behavior
          "activeTimeRange": [ # Range of time(s) specifying when condition is active. Maximum of 10 time ranges.
            { # Used for time-dependent conditions.
              "endTime": "A String", # End of time range. Range is inclusive. Must be in the future.
              "startTime": "A String", # Start of time range. Range is inclusive.
            },
          ],
          "queryRegex": "A String", # Optional. Query regex to match the whole search query. Cannot be set when Condition.query_terms is set. Only supported for Basic Site Search promotion serving controls.
          "queryTerms": [ # Search only A list of terms to match the query on. Cannot be set when Condition.query_regex is set. Maximum of 10 query terms.
            { # Matcher for search request query
              "fullMatch": True or False, # Whether the search query needs to exactly match the query term.
              "value": "A String", # The specific query value to match against Must be lowercase, must be UTF-8. Can have at most 3 space separated terms if full_match is true. Cannot be an empty string. Maximum length of 5000 characters.
            },
          ],
        },
      ],
      "displayName": "A String", # Required. Human readable name. The identifier used in UI views. Must be UTF-8 encoded string. Length limit is 128 characters. Otherwise an INVALID ARGUMENT error is thrown.
      "filterAction": { # Specified which products may be included in results. Uses same filter as boost. # Defines a filter-type control Currently not supported by Recommendation
        "dataStore": "A String", # Required. Specifies which data store's documents can be filtered by this control. Full data store name e.g. projects/123/locations/global/collections/default_collection/dataStores/default_data_store
        "filter": "A String", # Required. A filter to apply on the matching condition results. Required Syntax documentation: https://cloud.google.com/retail/docs/filter-and-order Maximum length is 5000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "name": "A String", # Immutable. Fully qualified name `projects/*/locations/global/dataStore/*/controls/*`
      "promoteAction": { # Promote certain links based on some trigger queries. Example: Promote shoe store link when searching for `shoe` keyword. The link can be outside of associated data store. # Promote certain links based on predefined trigger queries.
        "dataStore": "A String", # Required. Data store with which this promotion is attached to.
        "searchLinkPromotion": { # Promotion proto includes uri and other helping information to display the promotion. # Required. Promotion attached to this action.
          "description": "A String", # Optional. The Promotion description. Maximum length: 200 characters.
          "document": "A String", # Optional. The Document the user wants to promote. For site search, leave unset and only populate uri. Can be set along with uri.
          "enabled": True or False, # Optional. The enabled promotion will be returned for any serving configs associated with the parent of the control this promotion is attached to. This flag is used for basic site search only.
          "imageUri": "A String", # Optional. The promotion thumbnail image url.
          "title": "A String", # Required. The title of the promotion. Maximum length: 160 characters.
          "uri": "A String", # Optional. The URL for the page the user wants to promote. Must be set for site search. For other verticals, this is optional.
        },
      },
      "redirectAction": { # Redirects a shopper to the provided URI. # Defines a redirect-type control.
        "redirectUri": "A String", # Required. The URI to which the shopper will be redirected. Required. URI must have length equal or less than 2000 characters. Otherwise an INVALID ARGUMENT error is thrown.
      },
      "solutionType": "A String", # Required. Immutable. What solution the control belongs to. Must be compatible with vertical of resource. Otherwise an INVALID ARGUMENT error is thrown.
      "synonymsAction": { # Creates a set of terms that will act as synonyms of one another. Example: "happy" will also be considered as "glad", "glad" will also be considered as "happy". # Treats a group of terms as synonyms of one another.
        "synonyms": [ # Defines a set of synonyms. Can specify up to 100 synonyms. Must specify at least 2 synonyms. Otherwise an INVALID ARGUMENT error is thrown.
          "A String",
        ],
      },
      "useCases": [ # Specifies the use case for the control. Affects what condition fields can be set. Only applies to SOLUTION_TYPE_SEARCH. Currently only allow one use case per control. Must be set when solution_type is SolutionType.SOLUTION_TYPE_SEARCH.
        "A String",
      ],
    }