third_party/googleapis/google/api/servicecontrol/v1/service_controller.proto

// Copyright 2016 Google Inc.
//
// 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.

syntax = "proto3";

package google.api.servicecontrol.v1;

import "google/api/annotations.proto";
import "google/api/servicecontrol/v1/check_error.proto";
import "google/api/servicecontrol/v1/operation.proto";
import "google/rpc/status.proto";

option cc_enable_arenas = true;
option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
option java_multiple_files = true;
option java_outer_classname = "ServiceControllerProto";
option java_package = "com.google.api.servicecontrol.v1";
option objc_class_prefix = "GASC";


// [Google Service Control API](/service-control/overview)
//
// Lets clients check and report operations against
// a [managed service][google.api.servicemanagement.v1.ManagedService].
service ServiceController {
  // Checks an operation with Google Service Control to decide whether
  // the given operation should proceed. It should be called before the
  // operation is executed.
  //
  // If feasible, the client should cache the check results and reuse them for
  // up to 60s. In case of server errors, the client may rely on the cached
  // results for longer time.
  //
  // This method requires the `servicemanagement.services.check` permission
  // on the specified service. For more information, see
  // [Google Cloud IAM](https://cloud.google.com/iam).
  rpc Check(CheckRequest) returns (CheckResponse) {
    option (google.api.http) = { post: "/v1/services/{service_name}:check" body: "*" };
  }

  // Reports operations to Google Service Control. It should be called
  // after the operation is completed.
  //
  // If feasible, the client should aggregate reporting data for up to 5s to
  // reduce API traffic. Limiting aggregation to 5s is to reduce data loss
  // during client crashes. Clients should carefully choose the aggregation
  // window to avoid data loss risk more than 0.01% for business and
  // compliance reasons.
  //
  // This method requires the `servicemanagement.services.report` permission
  // on the specified service. For more information, see
  // [Google Cloud IAM](https://cloud.google.com/iam).
  rpc Report(ReportRequest) returns (ReportResponse) {
    option (google.api.http) = { post: "/v1/services/{service_name}:report" body: "*" };
  }
}

// Request message for the Check method.
message CheckRequest {
  // The service name as specified in its service configuration. For example,
  // `"pubsub.googleapis.com"`.
  //
  // See [google.api.Service][google.api.Service] for the definition of a service name.
  string service_name = 1;

  // The operation to be checked.
  Operation operation = 2;

  // Specifies which version of service configuration should be used to process
  // the request.
  //
  // If unspecified or no matching version can be found, the
  // latest one will be used.
  string service_config_id = 4;
}

// Response message for the Check method.
message CheckResponse {
  // The same operation_id value used in the CheckRequest.
  // Used for logging and diagnostics purposes.
  string operation_id = 1;

  // 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.
  repeated CheckError check_errors = 2;

  // The actual config id used to process the request.
  string service_config_id = 5;
}

// Request message for the Report method.
message ReportRequest {
  // The service name as specified in its service configuration. For example,
  // `"pubsub.googleapis.com"`.
  //
  // See [google.api.Service][google.api.Service] for the definition of a service name.
  string service_name = 1;

  // 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][google.api.servicecontrol.v1.ReportResponse.report_errors] for
  // partial failure behavior.
  repeated Operation operations = 2;

  // Specifies which version of service config should be used to process the
  // request.
  //
  // If unspecified or no matching version can be found, the
  // latest one will be used.
  string service_config_id = 3;
}

// Response message for the Report method.
message ReportResponse {
  // Represents the processing error of one `Operation` in the request.
  message ReportError {
    // The [Operation.operation_id][google.api.servicecontrol.v1.Operation.operation_id] value from the request.
    string operation_id = 1;

    // Details of the error when processing the `Operation`.
    google.rpc.Status status = 2;
  }

  // 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.
  repeated ReportError report_errors = 1;

  // The actual config id used to process the request.
  string service_config_id = 2;
}