google/api/servicecontrol/v1/service_controller.proto

// Copyright 2017 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](https://cloud.google.com/service-management/reference/rpc/google.api/servicemanagement.v1#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
  // 60 seconds. In case of server errors, the client can rely on the cached
  // results for longer time.
  //
  // NOTE: the [CheckRequest][google.api.servicecontrol.v1.CheckRequest] has the size limit of 64KB.
  //
  // 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 operation results to Google Service Control, such as logs and
  // metrics. It should be called after an operation is completed.
  //
  // If feasible, the client should aggregate reporting data for up to 5
  // seconds to reduce API traffic. Limiting aggregation to 5 seconds is to
  // reduce data loss during client crashes. Clients should carefully choose
  // the aggregation time window to avoid data loss risk more than 0.01%
  // for business and compliance reasons.
  //
  // NOTE: the [ReportRequest][google.api.servicecontrol.v1.ReportRequest] has the size limit of 1MB.
  //
  // 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](https://cloud.google.com/service-management/reference/rpc/google.api#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 {
  message CheckInfo {
    // Consumer info of this check.
    ConsumerInfo consumer_info = 2;
  }

  // `ConsumerInfo` provides information about the consumer project.
  message ConsumerInfo {
    // The Google cloud project number, e.g. 1234567890. A value of 0 indicates
    // no project number is found.
    int64 project_number = 1;
  }

  // The same operation_id value used in the [CheckRequest][google.api.servicecontrol.v1.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;

  // Feedback data returned from the server during processing a Check request.
  CheckInfo check_info = 6;
}

// 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](https://cloud.google.com/service-management/reference/rpc/google.api#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][google.api.servicecontrol.v1.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.api.servicecontrol.v1.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 general non-deterministic failure.
  //    When this happens, it's impossible to know which of the
  //    'Operations' in the request succeeded or failed.
  repeated ReportError report_errors = 1;

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