0
# Service Discovery and Information
1
2
Query and discovery operations for listing services, retrieving service configurations, and batch information retrieval across Google Cloud projects.
3
4
## Capabilities
5
6
### Get Service
7
8
Retrieves detailed information about a specific Google Cloud service, including its configuration and current state.
9
10
```python { .api }
11
def get_service(
12
request: GetServiceRequest,
13
*,
14
retry: OptionalRetry = gapic_v1.method.DEFAULT,
15
timeout: Optional[float] = None,
16
metadata: Sequence[Tuple[str, str]] = ()
17
) -> Service:
18
"""
19
Get information about a specific service.
20
21
Args:
22
request: The request object containing the service name
23
retry: Retry configuration for the request
24
timeout: Request timeout in seconds
25
metadata: Additional metadata for the request
26
27
Returns:
28
Service object with full configuration details
29
30
Raises:
31
google.api_core.exceptions.NotFound: If the service doesn't exist
32
google.api_core.exceptions.GoogleAPICallError: If the request fails
33
"""
34
```
35
36
Usage example:
37
38
```python
39
from google.cloud import service_usage
40
41
client = service_usage.ServiceUsageClient()
42
43
# Get detailed information about a service
44
service_name = "projects/my-project-id/services/storage.googleapis.com"
45
request = service_usage.GetServiceRequest(name=service_name)
46
47
service = client.get_service(request=request)
48
print(f"Service: {service.name}")
49
print(f"Title: {service.config.title}")
50
print(f"State: {service.state}")
51
print(f"Documentation: {service.config.documentation.summary}")
52
53
# Access service endpoints
54
for endpoint in service.config.endpoints:
55
print(f"Endpoint: {endpoint.name} - {endpoint.target}")
56
```
57
58
### List Services
59
60
Lists all services available to a project with optional filtering and pagination support.
61
62
```python { .api }
63
def list_services(
64
request: ListServicesRequest,
65
*,
66
retry: OptionalRetry = gapic_v1.method.DEFAULT,
67
timeout: Optional[float] = None,
68
metadata: Sequence[Tuple[str, str]] = ()
69
) -> ListServicesPager:
70
"""
71
List services available to a project.
72
73
Args:
74
request: The request object with parent, filter, and pagination options
75
retry: Retry configuration for the request
76
timeout: Request timeout in seconds
77
metadata: Additional metadata for the request
78
79
Returns:
80
Paginated iterator over Service objects
81
82
Raises:
83
google.api_core.exceptions.GoogleAPICallError: If the request fails
84
"""
85
```
86
87
Usage example:
88
89
```python
90
from google.cloud import service_usage
91
92
client = service_usage.ServiceUsageClient()
93
94
# List all services for a project
95
parent = "projects/my-project-id"
96
request = service_usage.ListServicesRequest(parent=parent)
97
98
# Iterate through all services
99
for service in client.list_services(request=request):
100
print(f"Service: {service.name}")
101
print(f"State: {service.state.name}")
102
103
# List only enabled services with filter
104
request_enabled = service_usage.ListServicesRequest(
105
parent=parent,
106
filter="state:ENABLED"
107
)
108
109
enabled_services = client.list_services(request=request_enabled)
110
print("Enabled services:")
111
for service in enabled_services:
112
print(f" {service.config.title}")
113
114
# Paginated listing with page size
115
request_paged = service_usage.ListServicesRequest(
116
parent=parent,
117
page_size=10
118
)
119
120
pager = client.list_services(request=request_paged)
121
for page in pager.pages:
122
print(f"Page with {len(page.services)} services:")
123
for service in page.services:
124
print(f" {service.name}")
125
```
126
127
### Batch Get Services
128
129
Retrieves information about multiple services in a single request, more efficient than individual get operations.
130
131
```python { .api }
132
def batch_get_services(
133
request: BatchGetServicesRequest,
134
*,
135
retry: OptionalRetry = gapic_v1.method.DEFAULT,
136
timeout: Optional[float] = None,
137
metadata: Sequence[Tuple[str, str]] = ()
138
) -> BatchGetServicesResponse:
139
"""
140
Get information about multiple services in a single request.
141
142
Args:
143
request: The request object containing parent and service names
144
retry: Retry configuration for the request
145
timeout: Request timeout in seconds
146
metadata: Additional metadata for the request
147
148
Returns:
149
BatchGetServicesResponse with list of services
150
151
Raises:
152
google.api_core.exceptions.GoogleAPICallError: If the request fails
153
"""
154
```
155
156
Usage example:
157
158
```python
159
from google.cloud import service_usage
160
161
client = service_usage.ServiceUsageClient()
162
163
# Get information about multiple services at once
164
parent = "projects/my-project-id"
165
service_names = [
166
f"{parent}/services/storage.googleapis.com",
167
f"{parent}/services/compute.googleapis.com",
168
f"{parent}/services/bigquery.googleapis.com"
169
]
170
171
request = service_usage.BatchGetServicesRequest(
172
parent=parent,
173
names=service_names
174
)
175
176
response = client.batch_get_services(request=request)
177
print(f"Retrieved {len(response.services)} services:")
178
179
for service in response.services:
180
print(f"Service: {service.config.title}")
181
print(f" Name: {service.name}")
182
print(f" State: {service.state.name}")
183
print(f" APIs: {len(service.config.apis)}")
184
```
185
186
## Request Types
187
188
```python { .api }
189
class GetServiceRequest:
190
"""Request to get a specific service."""
191
name: str # Format: "projects/{project}/services/{service}"
192
193
class ListServicesRequest:
194
"""Request to list services."""
195
parent: str # Format: "projects/{project}"
196
page_size: int # Maximum number of services per page
197
page_token: str # Token for pagination
198
filter: str # Filter expression (e.g., "state:ENABLED")
199
200
class BatchGetServicesRequest:
201
"""Request to get multiple services."""
202
parent: str # Format: "projects/{project}"
203
names: List[str] # Full service resource names
204
```
205
206
## Response Types
207
208
```python { .api }
209
class ListServicesResponse:
210
"""Response from listing services."""
211
services: List[Service] # List of services
212
next_page_token: str # Token for next page
213
214
class BatchGetServicesResponse:
215
"""Response from batch getting services."""
216
services: List[Service] # List of requested services
217
```
218
219
## Pager Classes
220
221
```python { .api }
222
class ListServicesPager:
223
"""Pager for iterating through list_services results."""
224
225
def __iter__(self) -> Iterator[Service]:
226
"""Iterate through Service objects."""
227
228
@property
229
def pages(self) -> Iterator[ListServicesResponse]:
230
"""Iterate through response pages."""
231
232
class ListServicesAsyncPager:
233
"""Async pager for iterating through list_services results."""
234
235
def __aiter__(self) -> AsyncIterator[Service]:
236
"""Async iterate through Service objects."""
237
238
@property
239
def pages(self) -> AsyncIterator[ListServicesResponse]:
240
"""Async iterate through response pages."""
241
```
242
243
## Filter Expressions
244
245
The `filter` parameter in `ListServicesRequest` supports the following expressions:
246
247
- `state:ENABLED` - Only enabled services
248
- `state:DISABLED` - Only disabled services
249
- `state:STATE_UNSPECIFIED` - Services with unspecified state
250
251
Multiple filters can be combined with logical operators:
252
- `state:ENABLED OR state:DISABLED` - All services with known state