xref: /aosp_15_r20/external/googleapis/google/api/servicecontrol/v2/servicecontrol.yaml (revision d5c09012810ac0c9f33fe448fb6da8260d444cc9)
1type: google.api.Service
2config_version: 3
3name: servicecontrol.googleapis.com
4title: Service Control API
5
6apis:
7- name: google.api.servicecontrol.v2.ServiceController
8
9documentation:
10  summary: |-
11    Provides admission control and telemetry reporting for services integrated
12    with Service Infrastructure.
13  overview: |-
14    Google Service Control provides control plane functionality to managed
15    services, such as logging, monitoring, and status checks. This page
16    provides an overview of what it does and how it works.
17
18    ## Why use Service Control?
19
20    When you develop a cloud service, you typically start with the business
21    requirements and the architecture design, then proceed with API definition
22    and implementation. Before you put your service into production, you
23    need to deal with many control plane issues:
24
25    * How to control access to your service.
26    * How to send logging and monitoring data to both consumers and producers.
27    * How to create and manage dashboards to visualize this data.
28    * How to automatically scale the control plane components with your
29    service.
30
31    Service Control is a mature and feature-rich control plane provider
32    that addresses these needs with high efficiency, high scalability,
33    and high availability. It provides a simple public API that can be
34    accessed from anywhere using JSON REST and gRPC clients, so when you move
35    your service from on-premise to a cloud provider, or from one cloud
36    provider to another, you don't need to change the control plane provider.
37
38    Services built using Google Cloud Endpoints already take advantage of
39    Service Control. Cloud Endpoints sends logging and monitoring data
40    through Google Service Control for every request arriving at its
41    proxy. If you need to report any additional logging and monitoring data
42    for your Cloud Endpoints service, you can call the Service Control API
43    directly from your service.
44
45    The Service Control API definition is open sourced and available on
46    [GitHub](https://github.com/googleapis/googleapis/tree/master/google/api/servicecontrol). By
47    changing the DNS name, you can easily use alternative implementations
48    of the Service Control API.
49
50    ## Architecture
51
52    Google Service Control works with a set of *managed services* and their
53    *operations* (activities), *checks* whether an operation is allowed to
54    proceed, and *reports* completed operations. Behind the scenes, it
55    leverages other
56    Google Cloud services, such as
57    [Google Service
58    Management](https://cloud.google.com/service-infrastructure/docs/service-management/getting-started), [Stackdriver
59    Logging](https://cloud.google.com/products/operations), and [Stackdriver
60    Monitoring](https://cloud.google.com/monitoring), while hiding their
61    complexity from service producers. It enables service
62    producers to send telemetry data to their consumers. It uses caching,
63    batching, aggregation, and retries to deliver higher performance and
64    availability than the individual backend systems it encapsulates.
65
66    <figure id="fig-arch" class="center">
67    <div style="width: 70%;margin: auto">
68    <img src="/service-infrastructure/docs/service-control/images/arch.svg"
69    alt="The overall architecture of a service that uses Google Service
70    Control."> </div> <figcaption><b>Figure 1</b>: Using Google Service
71    Control.</figcaption> </figure>
72
73    The Service Control API provides two methods:
74
75    *
76    [`services.check`](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services/check),
77    used for:
78    * Ensuring valid consumer status
79    * Validating API keys
80    *
81    [`services.report`](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services/report),
82    used for:
83    * Sending logs to Stackdriver Logging
84    * Sending metrics to Stackdriver Monitoring
85
86    We'll look at these in more detail in the rest of this overview.
87
88    ## Managed services
89
90    A [managed
91    service](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services) is
92    a network service managed by
93    [Google Service
94    Management](https://cloud.google.com/service-infrastructure/docs/service-management/getting-started). Each
95    managed service has a unique name, such as `example.googleapis.com`,
96    which must be a valid fully-qualified DNS name, as per RFC 1035.
97
98    For example:
99
100    * Google Cloud Pub/Sub (`pubsub.googleapis.com`)
101    * Google Cloud Vision (`vision.googleapis.com`)
102    * Google Cloud Bigtable (`bigtable.googleapis.com`)
103    * Google Cloud Datastore (`datastore.googleapis.com`)
104
105    Google Service Management manages the lifecycle of each service's
106    configuration, which is used to customize Google Service Control's
107    behavior. Service configurations are also used by Google Cloud Console for
108    displaying APIs and their settings, enabling/disabling APIs, and more.
109
110    ## Operations
111
112    Google Service Control uses the generic concept of an *operation*
113    to represent the activities of a managed service, such as API calls and
114    resource usage. Each operation is associated with a managed service and a
115    specific service consumer, and has a set of properties that describe the
116    operation, such as the API method name and resource usage amount. For more
117    information, see the
118    [Operation
119    definition](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/Operation). ##
120    Check
121
122    The
123    [`services.check`](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services/check) method
124    determines whether an operation should be allowed to proceed for a
125    managed service.
126
127    For example:
128
129    * Check if the consumer is still active.
130    * Check if the consumer has enabled the service.
131    * Check if the API key is still valid.
132
133    By performing multiple checks within a single method call, it provides
134    better performance, higher reliability, and reduced development cost to
135    service producers compared to checking with multiple backend systems.
136
137    ## Report
138
139    The
140    [`services.report`](https://cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services/report) method
141    reports completed operations for a managed service to backend
142    systems, such as logging and monitoring. The reported data can be seen in
143    Google API Console and Google Cloud Console, and retrieved with
144    appropriate APIs, such as the Stackdriver Logging and Stackdriver
145    Monitoring APIs.
146
147    ## Next steps
148
149    * Read our [Getting Started
150    guide](https://cloud.google.com/service-infrastructure/docs/service-control/getting-started)
151    to find out how to set up and use the Google Service Control API.
152
153backend:
154  rules:
155  - selector: google.api.servicecontrol.v2.ServiceController.Check
156    deadline: 5.0
157  - selector: google.api.servicecontrol.v2.ServiceController.Report
158    deadline: 5.0
159
160authentication:
161  rules:
162  - selector: google.api.servicecontrol.v2.ServiceController.Check
163    oauth:
164      canonical_scopes: |-
165        https://www.googleapis.com/auth/cloud-platform,
166        https://www.googleapis.com/auth/servicecontrol
167  - selector: google.api.servicecontrol.v2.ServiceController.Report
168    oauth:
169      canonical_scopes: |-
170        https://www.googleapis.com/auth/cloud-platform,
171        https://www.googleapis.com/auth/servicecontrol
172