googleapis/google/api/usage.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;

option java_multiple_files = true;
option java_outer_classname = "UsageProto";
option java_package = "com.google.api";


// Configuration controlling usage of a service.
message Usage {
  // Service access types.
  //
  // Access to restricted API features is always controlled by
  // [visibility][google.api.Visibility], independent of the ServiceAccess type.
  //
  enum ServiceAccess {
    // The service can only be seen/used by users identified in the service's
    // access control policy.
    //
    // If the service has not been whitelisted by your domain administrator
    // for out-of-org publishing, then this mode will be treated like
    // ORG_RESTRICTED.
    RESTRICTED = 0;

    // The service can be seen/used by anyone.
    //
    // If the service has not been whitelisted by your domain administrator
    // for out-of-org publishing, then this mode will be treated like
    // ORG_PUBLIC.
    //
    // The discovery document for the service will also be public and allow
    // unregistered access.
    PUBLIC = 1;

    // The service can be seen/used by users identified in the service's
    // access control policy and they are within the organization that owns the
    // service.
    //
    // Access is further constrained to the group
    // controlled by the administrator of the project/org that owns the
    // service.
    ORG_RESTRICTED = 2;

    // The service can be seen/used by the group of users controlled by the
    // administrator of the project/org that owns the service.
    ORG_PUBLIC = 3;
  }

  // Controls which users can see or activate the service.
  ServiceAccess service_access = 4;

  // Requirements that must be satisfied before a consumer project can use the
  // service. Each requirement is of the form <service.name>/<requirement-id>;
  // for example 'serviceusage.googleapis.com/billing-enabled'.
  repeated string requirements = 1;

  // Services that must be activated in order for this service to be used.
  // The set of services activated as a result of these relations are all
  // activated in parallel with no guaranteed order of activation.
  // Each string is a service name, e.g. `calendar.googleapis.com`.
  repeated string depends_on_services = 2;

  // Services that must be contacted before a consumer can begin using the
  // service. Each service will be contacted in sequence, and, if any activation
  // call fails, the entire activation will fail. Each hook is of the form
  // <service.name>/<hook-id>, where <hook-id> is optional; for example:
  // 'robotservice.googleapis.com/default'.
  repeated string activation_hooks = 3;

  // Services that must be contacted before a consumer can deactivate a
  // service. Each service will be contacted in sequence, and, if any
  // deactivation call fails, the entire deactivation will fail. Each hook is
  // of the form <service.name>/<hook-id>, where <hook-id> is optional; for
  // example:
  // 'compute.googleapis.com/'.
  repeated string deactivation_hooks = 5;

  // Individual rules for configuring usage on selected methods.
  repeated UsageRule rules = 6;
}

// Usage configuration rules for the service.
//
// NOTE: Under development.
//
//
// Use this rule to configure unregistered calls for the service. Unregistered
// calls are calls that do not contain consumer project identity.
// (Example: calls that do not contain an API key).
// By default, API methods do not allow unregistered calls, and each method call
// must be identified by a consumer project identity. Use this rule to
// allow/disallow unregistered calls.
//
// Example of an API that wants to allow unregistered calls for entire service.
//
//     usage:
//       rules:
//       - selector: "*"
//         allow_unregistered_calls: true
//
// Example of a method that wants to allow unregistered calls.
//
//     usage:
//       rules:
//       - selector: "google.example.library.v1.LibraryService.CreateBook"
//         allow_unregistered_calls: true
message UsageRule {
  // Selects the methods to which this rule applies. Use '*' to indicate all
  // methods in all APIs.
  //
  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
  string selector = 1;

  // True, if the method allows unregistered calls; false otherwise.
  bool allow_unregistered_calls = 2;
}