Google Service Control API . services

Instance Methods

check(serviceName=None, body, x__xgafv=None)

Checks an operation with Google Service Control to decide whether

report(serviceName=None, body, x__xgafv=None)

Reports operations to Google Service Control. It should be called

Method Details

check(serviceName=None, body, x__xgafv=None)
Checks an operation with Google Service Control to decide whether
the given operation should proceed. It should be called before the
operation is executed.

This method requires the `servicemanagement.services.check` permission
on the specified service. For more information, see
[Google Cloud IAM](https://cloud.google.com/iam).

Args:
  serviceName: string, The service name as specified in its service configuration. For example,
`"pubsub.googleapis.com"`.

See google.api.Service for the definition of a service name. (required)
  body: object, The request body. (required)
    The object takes the form of:

{ # Request message for the Check method.
    "operation": { # Represents information regarding an operation. # The operation to be checked.
      "operationName": "A String", # Fully qualified name of the operation. Reserved for future use.
      "metricValueSets": [ # Represents information about this operation. Each MetricValueSet
          # corresponds to a metric defined in the service configuration.
          # The data type used in the MetricValueSet must agree with
          # the data type specified in the metric definition.
          #
          # Within a single operation, it is not allowed to have more than one
          # MetricValue instances that have the same metric names and identical
          # label value combinations. If a request has such duplicated MetricValue
          # instances, the entire request is rejected with
          # an invalid argument error.
        { # Represents a set of metric values in the same metric.
            # Each metric value in the set should have a unique combination of start time,
            # end time, and label values.
          "metricValues": [ # The values in this metric.
            { # Represents a single metric value.
              "labels": { # The labels describing the metric value.
                  # See comments on google.api.servicecontrol.v1.Operation.labels for
                  # the overriding relationship.
                "a_key": "A String",
              },
              "doubleValue": 3.14, # A double precision floating point value.
              "boolValue": True or False, # A boolean value.
              "startTime": "A String", # The start of the time period over which this metric value's measurement
                  # applies. The time period has different semantics for different metric
                  # types (cumulative, delta, and gauge). See the metric definition
                  # documentation in the service configuration for details.
              "distributionValue": { # Distribution represents a frequency distribution of double-valued sample # A distribution value.
                  # points. It contains the size of the population of sample points plus
                  # additional optional information:
                  #
                  #   - the arithmetic mean of the samples
                  #   - the minimum and maximum of the samples
                  #   - the sum-squared-deviation of the samples, used to compute variance
                  #   - a histogram of the values of the sample points
                "count": "A String", # The total number of samples in the distribution. Must be >= 0.
                "bucketCounts": [ # The number of samples in each histogram bucket. `bucket_counts` are
                    # optional. If present, they must sum to the `count` value.
                    #
                    # The buckets are defined below in `bucket_option`. There are N buckets.
                    # `bucket_counts[0]` is the number of samples in the underflow bucket.
                    # `bucket_counts[1]` to `bucket_counts[N-1]` are the numbers of samples
                    # in each of the finite buckets. And `bucket_counts[N] is the number
                    # of samples in the overflow bucket. See the comments of `bucket_option`
                    # below for more details.
                    #
                    # Any suffix of trailing zeros may be omitted.
                  "A String",
                ],
                "exponentialBuckets": { # Describing buckets with exponentially growing width. # Buckets with exponentially growing width.
                  "scale": 3.14, # The i'th exponential bucket covers the interval
                      #   [scale * growth_factor^(i-1), scale * growth_factor^i)
                      # where i ranges from 1 to num_finite_buckets inclusive.
                      # Must be > 0.
                  "growthFactor": 3.14, # The i'th exponential bucket covers the interval
                      #   [scale * growth_factor^(i-1), scale * growth_factor^i)
                      # where i ranges from 1 to num_finite_buckets inclusive.
                      # Must be larger than 1.0.
                  "numFiniteBuckets": 42, # The number of finite buckets. With the underflow and overflow buckets,
                      # the total number of buckets is `num_finite_buckets` + 2.
                      # See comments on `bucket_options` for details.
                },
                "minimum": 3.14, # The minimum of the population of values. Ignored if `count` is zero.
                "maximum": 3.14, # The maximum of the population of values. Ignored if `count` is zero.
                "sumOfSquaredDeviation": 3.14, # The sum of squared deviations from the mean:
                    #   Sum[i=1..count]((x_i - mean)^2)
                    # where each x_i is a sample values. If `count` is zero then this field
                    # must be zero, otherwise validation of the request fails.
                "linearBuckets": { # Describing buckets with constant width. # Buckets with constant width.
                  "width": 3.14, # The i'th linear bucket covers the interval
                      #   [offset + (i-1) * width, offset + i * width)
                      # where i ranges from 1 to num_finite_buckets, inclusive.
                      # Must be strictly positive.
                  "numFiniteBuckets": 42, # The number of finite buckets. With the underflow and overflow buckets,
                      # the total number of buckets is `num_finite_buckets` + 2.
                      # See comments on `bucket_options` for details.
                  "offset": 3.14, # The i'th linear bucket covers the interval
                      #   [offset + (i-1) * width, offset + i * width)
                      # where i ranges from 1 to num_finite_buckets, inclusive.
                },
                "explicitBuckets": { # Describing buckets with arbitrary user-provided width. # Buckets with arbitrary user-provided width.
                  "bounds": [ # 'bound' is a list of strictly increasing boundaries between
                      # buckets. Note that a list of length N-1 defines N buckets because
                      # of fenceposting. See comments on `bucket_options` for details.
                      #
                      # The i'th finite bucket covers the interval
                      #   [bound[i-1], bound[i])
                      # where i ranges from 1 to bound_size() - 1. Note that there are no
                      # finite buckets at all if 'bound' only contains a single element; in
                      # that special case the single bound defines the boundary between the
                      # underflow and overflow buckets.
                      #
                      # bucket number                   lower bound    upper bound
                      #  i == 0 (underflow)              -inf           bound[i]
                      #  0 < i < bound_size()            bound[i-1]     bound[i]
                      #  i == bound_size() (overflow)    bound[i-1]     +inf
                    3.14,
                  ],
                },
                "mean": 3.14, # The arithmetic mean of the samples in the distribution. If `count` is
                    # zero then this field must be zero.
              },
              "stringValue": "A String", # A text string value.
              "int64Value": "A String", # A signed 64-bit integer value.
              "endTime": "A String", # The end of the time period over which this metric value's measurement
                  # applies.
            },
          ],
          "metricName": "A String", # The metric name defined in the service configuration.
        },
      ],
      "importance": "A String", # DO NOT USE. This is an experimental field.
      "labels": { # Labels describing the operation. Only the following labels are allowed:
          #
          # - Labels describing monitored resources as defined in
          #   the service configuration.
          # - Default labels of metric values. When specified, labels defined in the
          #   metric value override these default.
          # - The following labels defined by Google Cloud Platform:
          #     - `cloud.googleapis.com/location` describing the location where the
          #        operation happened,
          #     - `servicecontrol.googleapis.com/user_agent` describing the user agent
          #        of the API request,
          #     - `servicecontrol.googleapis.com/service_agent` describing the service
          #        used to handle the API request (e.g. ESP),
          #     - `servicecontrol.googleapis.com/platform` describing the platform
          #        where the API is served (e.g. GAE, GCE, GKE).
        "a_key": "A String",
      },
      "consumerId": "A String", # Identity of the consumer who is using the service.
          # This field should be filled in for the operations initiated by a
          # consumer, but not for service-initiated operations that are
          # not related to a specific consumer.
          #
          # This can be in one of the following formats:
          #   project:,
          #   project_number:,
          #   api_key:.
      "logEntries": [ # Represents information to be logged.
        { # An individual log entry.
          "name": "A String", # Required. The log to which this log entry belongs. Examples: `"syslog"`,
              # `"book_log"`.
          "textPayload": "A String", # The log entry payload, represented as a Unicode string (UTF-8).
          "timestamp": "A String", # The time the event described by the log entry occurred. If
              # omitted, defaults to operation start time.
          "labels": { # A set of user-defined (key, value) data that provides additional
              # information about the log entry.
            "a_key": "A String",
          },
          "structPayload": { # The log entry payload, represented as a structure that
              # is expressed as a JSON object.
            "a_key": "", # Properties of the object.
          },
          "insertId": "A String", # A unique ID for the log entry used for deduplication. If omitted,
              # the implementation will generate one based on operation_id.
          "protoPayload": { # The log entry payload, represented as a protocol buffer that is
              # expressed as a JSON object. You can only pass `protoPayload`
              # values that belong to a set of approved types.
            "a_key": "", # Properties of the object. Contains field @type with type URL.
          },
          "severity": "A String", # The severity of the log entry. The default value is
              # `LogSeverity.DEFAULT`.
        },
      ],
      "startTime": "A String", # Required. Start time of the operation.
      "endTime": "A String", # End time of the operation.
          # Required when the operation is used in ServiceController.Report,
          # but optional when the operation is used in ServiceController.Check.
      "operationId": "A String", # Identity of the operation. This must be unique within the scope of the
          # service that generated the operation. If the service calls
          # Check() and Report() on the same operation, the two calls should carry
          # the same id.
          #
          # UUID version 4 is recommended, though not required.
          # In scenarios where an operation is computed from existing information
          # and an idempotent id is desirable for deduplication purpose, UUID version 5
          # is recommended. See RFC 4122 for details.
    },
  }

  x__xgafv: string, V1 error format.
    Allowed values
      1 - v1 error format
      2 - v2 error format

Returns:
  An object of the form:

    { # Response message for the Check method.
    "serviceConfigId": "A String", # The actual config id used to process the request.
    "checkErrors": [ # Indicate the decision of the check.
        #
        # If no check errors are present, the service should process the operation.
        # Otherwise the service should use the list of errors to determine the
        # appropriate action.
      { # Defines the errors to be returned in
          # google.api.servicecontrol.v1.CheckResponse.check_errors.
        "code": "A String", # The error code.
        "detail": "A String", # Free-form text providing details on the error cause of the error.
      },
    ],
    "operationId": "A String", # The same operation_id value used in the CheckRequest.
        # Used for logging and diagnostics purposes.
  }
report(serviceName=None, body, x__xgafv=None)
Reports operations to Google Service Control. It should be called
after the operation is completed.

This method requires the `servicemanagement.services.report` permission
on the specified service. For more information, see
[Google Cloud IAM](https://cloud.google.com/iam).

Args:
  serviceName: string, The service name as specified in its service configuration. For example,
`"pubsub.googleapis.com"`.

See google.api.Service for the definition of a service name. (required)
  body: object, The request body. (required)
    The object takes the form of:

{ # Request message for the Report method.
    "operations": [ # Operations to be reported.
        # 
        # Typically the service should report one operation per request.
        # Putting multiple operations into a single request is allowed, but should
        # be used only when multiple operations are natually available at the time
        # of the report.
        # 
        # If multiple operations are in a single request, the total request size
        # should be no larger than 1MB. See ReportResponse.report_errors for
        # partial failure behavior.
      { # Represents information regarding an operation.
        "operationName": "A String", # Fully qualified name of the operation. Reserved for future use.
        "metricValueSets": [ # Represents information about this operation. Each MetricValueSet
            # corresponds to a metric defined in the service configuration.
            # The data type used in the MetricValueSet must agree with
            # the data type specified in the metric definition.
            #
            # Within a single operation, it is not allowed to have more than one
            # MetricValue instances that have the same metric names and identical
            # label value combinations. If a request has such duplicated MetricValue
            # instances, the entire request is rejected with
            # an invalid argument error.
          { # Represents a set of metric values in the same metric.
              # Each metric value in the set should have a unique combination of start time,
              # end time, and label values.
            "metricValues": [ # The values in this metric.
              { # Represents a single metric value.
                "labels": { # The labels describing the metric value.
                    # See comments on google.api.servicecontrol.v1.Operation.labels for
                    # the overriding relationship.
                  "a_key": "A String",
                },
                "doubleValue": 3.14, # A double precision floating point value.
                "boolValue": True or False, # A boolean value.
                "startTime": "A String", # The start of the time period over which this metric value's measurement
                    # applies. The time period has different semantics for different metric
                    # types (cumulative, delta, and gauge). See the metric definition
                    # documentation in the service configuration for details.
                "distributionValue": { # Distribution represents a frequency distribution of double-valued sample # A distribution value.
                    # points. It contains the size of the population of sample points plus
                    # additional optional information:
                    #
                    #   - the arithmetic mean of the samples
                    #   - the minimum and maximum of the samples
                    #   - the sum-squared-deviation of the samples, used to compute variance
                    #   - a histogram of the values of the sample points
                  "count": "A String", # The total number of samples in the distribution. Must be >= 0.
                  "bucketCounts": [ # The number of samples in each histogram bucket. `bucket_counts` are
                      # optional. If present, they must sum to the `count` value.
                      #
                      # The buckets are defined below in `bucket_option`. There are N buckets.
                      # `bucket_counts[0]` is the number of samples in the underflow bucket.
                      # `bucket_counts[1]` to `bucket_counts[N-1]` are the numbers of samples
                      # in each of the finite buckets. And `bucket_counts[N] is the number
                      # of samples in the overflow bucket. See the comments of `bucket_option`
                      # below for more details.
                      #
                      # Any suffix of trailing zeros may be omitted.
                    "A String",
                  ],
                  "exponentialBuckets": { # Describing buckets with exponentially growing width. # Buckets with exponentially growing width.
                    "scale": 3.14, # The i'th exponential bucket covers the interval
                        #   [scale * growth_factor^(i-1), scale * growth_factor^i)
                        # where i ranges from 1 to num_finite_buckets inclusive.
                        # Must be > 0.
                    "growthFactor": 3.14, # The i'th exponential bucket covers the interval
                        #   [scale * growth_factor^(i-1), scale * growth_factor^i)
                        # where i ranges from 1 to num_finite_buckets inclusive.
                        # Must be larger than 1.0.
                    "numFiniteBuckets": 42, # The number of finite buckets. With the underflow and overflow buckets,
                        # the total number of buckets is `num_finite_buckets` + 2.
                        # See comments on `bucket_options` for details.
                  },
                  "minimum": 3.14, # The minimum of the population of values. Ignored if `count` is zero.
                  "maximum": 3.14, # The maximum of the population of values. Ignored if `count` is zero.
                  "sumOfSquaredDeviation": 3.14, # The sum of squared deviations from the mean:
                      #   Sum[i=1..count]((x_i - mean)^2)
                      # where each x_i is a sample values. If `count` is zero then this field
                      # must be zero, otherwise validation of the request fails.
                  "linearBuckets": { # Describing buckets with constant width. # Buckets with constant width.
                    "width": 3.14, # The i'th linear bucket covers the interval
                        #   [offset + (i-1) * width, offset + i * width)
                        # where i ranges from 1 to num_finite_buckets, inclusive.
                        # Must be strictly positive.
                    "numFiniteBuckets": 42, # The number of finite buckets. With the underflow and overflow buckets,
                        # the total number of buckets is `num_finite_buckets` + 2.
                        # See comments on `bucket_options` for details.
                    "offset": 3.14, # The i'th linear bucket covers the interval
                        #   [offset + (i-1) * width, offset + i * width)
                        # where i ranges from 1 to num_finite_buckets, inclusive.
                  },
                  "explicitBuckets": { # Describing buckets with arbitrary user-provided width. # Buckets with arbitrary user-provided width.
                    "bounds": [ # 'bound' is a list of strictly increasing boundaries between
                        # buckets. Note that a list of length N-1 defines N buckets because
                        # of fenceposting. See comments on `bucket_options` for details.
                        #
                        # The i'th finite bucket covers the interval
                        #   [bound[i-1], bound[i])
                        # where i ranges from 1 to bound_size() - 1. Note that there are no
                        # finite buckets at all if 'bound' only contains a single element; in
                        # that special case the single bound defines the boundary between the
                        # underflow and overflow buckets.
                        #
                        # bucket number                   lower bound    upper bound
                        #  i == 0 (underflow)              -inf           bound[i]
                        #  0 < i < bound_size()            bound[i-1]     bound[i]
                        #  i == bound_size() (overflow)    bound[i-1]     +inf
                      3.14,
                    ],
                  },
                  "mean": 3.14, # The arithmetic mean of the samples in the distribution. If `count` is
                      # zero then this field must be zero.
                },
                "stringValue": "A String", # A text string value.
                "int64Value": "A String", # A signed 64-bit integer value.
                "endTime": "A String", # The end of the time period over which this metric value's measurement
                    # applies.
              },
            ],
            "metricName": "A String", # The metric name defined in the service configuration.
          },
        ],
        "importance": "A String", # DO NOT USE. This is an experimental field.
        "labels": { # Labels describing the operation. Only the following labels are allowed:
            #
            # - Labels describing monitored resources as defined in
            #   the service configuration.
            # - Default labels of metric values. When specified, labels defined in the
            #   metric value override these default.
            # - The following labels defined by Google Cloud Platform:
            #     - `cloud.googleapis.com/location` describing the location where the
            #        operation happened,
            #     - `servicecontrol.googleapis.com/user_agent` describing the user agent
            #        of the API request,
            #     - `servicecontrol.googleapis.com/service_agent` describing the service
            #        used to handle the API request (e.g. ESP),
            #     - `servicecontrol.googleapis.com/platform` describing the platform
            #        where the API is served (e.g. GAE, GCE, GKE).
          "a_key": "A String",
        },
        "consumerId": "A String", # Identity of the consumer who is using the service.
            # This field should be filled in for the operations initiated by a
            # consumer, but not for service-initiated operations that are
            # not related to a specific consumer.
            #
            # This can be in one of the following formats:
            #   project:,
            #   project_number:,
            #   api_key:.
        "logEntries": [ # Represents information to be logged.
          { # An individual log entry.
            "name": "A String", # Required. The log to which this log entry belongs. Examples: `"syslog"`,
                # `"book_log"`.
            "textPayload": "A String", # The log entry payload, represented as a Unicode string (UTF-8).
            "timestamp": "A String", # The time the event described by the log entry occurred. If
                # omitted, defaults to operation start time.
            "labels": { # A set of user-defined (key, value) data that provides additional
                # information about the log entry.
              "a_key": "A String",
            },
            "structPayload": { # The log entry payload, represented as a structure that
                # is expressed as a JSON object.
              "a_key": "", # Properties of the object.
            },
            "insertId": "A String", # A unique ID for the log entry used for deduplication. If omitted,
                # the implementation will generate one based on operation_id.
            "protoPayload": { # The log entry payload, represented as a protocol buffer that is
                # expressed as a JSON object. You can only pass `protoPayload`
                # values that belong to a set of approved types.
              "a_key": "", # Properties of the object. Contains field @type with type URL.
            },
            "severity": "A String", # The severity of the log entry. The default value is
                # `LogSeverity.DEFAULT`.
          },
        ],
        "startTime": "A String", # Required. Start time of the operation.
        "endTime": "A String", # End time of the operation.
            # Required when the operation is used in ServiceController.Report,
            # but optional when the operation is used in ServiceController.Check.
        "operationId": "A String", # Identity of the operation. This must be unique within the scope of the
            # service that generated the operation. If the service calls
            # Check() and Report() on the same operation, the two calls should carry
            # the same id.
            #
            # UUID version 4 is recommended, though not required.
            # In scenarios where an operation is computed from existing information
            # and an idempotent id is desirable for deduplication purpose, UUID version 5
            # is recommended. See RFC 4122 for details.
      },
    ],
  }

  x__xgafv: string, V1 error format.
    Allowed values
      1 - v1 error format
      2 - v2 error format

Returns:
  An object of the form:

    { # Response message for the Report method.
    "serviceConfigId": "A String", # The actual config id used to process the request.
    "reportErrors": [ # Partial failures, one for each `Operation` in the request that failed
        # processing. There are three possible combinations of the RPC status:
        #
        # 1. The combination of a successful RPC status and an empty `report_errors`
        #    list indicates a complete success where all `Operations` in the
        #    request are processed successfully.
        # 2. The combination of a successful RPC status and a non-empty
        #    `report_errors` list indicates a partial success where some
        #    `Operations` in the request succeeded. Each
        #    `Operation` that failed processing has a corresponding item
        #    in this list.
        # 3. A failed RPC status indicates a complete failure where none of the
        #    `Operations` in the request succeeded.
      { # Represents the processing error of one `Operation` in the request.
        "status": { # The `Status` type defines a logical error model that is suitable for different # Details of the error when processing the `Operation`.
            # programming environments, including REST APIs and RPC APIs. It is used by
            # [gRPC](https://github.com/grpc). The error model is designed to be:
            #
            # - Simple to use and understand for most users
            # - Flexible enough to meet unexpected needs
            #
            # # Overview
            #
            # The `Status` message contains three pieces of data: error code, error message,
            # and error details. The error code should be an enum value of
            # google.rpc.Code, but it may accept additional error codes if needed.  The
            # error message should be a developer-facing English message that helps
            # developers *understand* and *resolve* the error. If a localized user-facing
            # error message is needed, put the localized message in the error details or
            # localize it in the client. The optional error details may contain arbitrary
            # information about the error. There is a predefined set of error detail types
            # in the package `google.rpc` which can be used for common error conditions.
            #
            # # Language mapping
            #
            # The `Status` message is the logical representation of the error model, but it
            # is not necessarily the actual wire format. When the `Status` message is
            # exposed in different client libraries and different wire protocols, it can be
            # mapped differently. For example, it will likely be mapped to some exceptions
            # in Java, but more likely mapped to some error codes in C.
            #
            # # Other uses
            #
            # The error model and the `Status` message can be used in a variety of
            # environments, either with or without APIs, to provide a
            # consistent developer experience across different environments.
            #
            # Example uses of this error model include:
            #
            # - Partial errors. If a service needs to return partial errors to the client,
            #     it may embed the `Status` in the normal response to indicate the partial
            #     errors.
            #
            # - Workflow errors. A typical workflow has multiple steps. Each step may
            #     have a `Status` message for error reporting purpose.
            #
            # - Batch operations. If a client uses batch request and batch response, the
            #     `Status` message should be used directly inside batch response, one for
            #     each error sub-response.
            #
            # - Asynchronous operations. If an API call embeds asynchronous operation
            #     results in its response, the status of those operations should be
            #     represented directly using the `Status` message.
            #
            # - Logging. If some API errors are stored in logs, the message `Status` could
            #     be used directly after any stripping needed for security/privacy reasons.
          "message": "A String", # A developer-facing error message, which should be in English. Any
              # user-facing error message should be localized and sent in the
              # google.rpc.Status.details field, or localized by the client.
          "code": 42, # The status code, which should be an enum value of google.rpc.Code.
          "details": [ # A list of messages that carry the error details.  There will be a
              # common set of message types for APIs to use.
            {
              "a_key": "", # Properties of the object. Contains field @type with type URL.
            },
          ],
        },
        "operationId": "A String", # The Operation.operation_id value from the request.
      },
    ],
  }