0
# Client Configuration
1

2
Configuration classes for customizing Google API client behavior, including authentication, endpoints, transport options, and client metadata. These utilities provide standardized ways to configure Google Cloud client libraries.
3

4
## Capabilities
5

6
### Client Options
7

8
Configuration class for customizing client behavior and transport settings.
9

10
```python { .api }
11
class ClientOptions:
12
    """
13
    Configuration options for Google API clients.
14
    
15
    Args:
16
        api_endpoint (str, optional): Custom API endpoint URL
17
        client_cert_source (Callable, optional): Function returning client certificate
18
        client_encrypted_cert_source (Callable, optional): Function returning encrypted client certificate
19
        quota_project_id (str, optional): Project ID for quota attribution
20
        credentials_file (str, optional): Path to service account credentials file
21
        scopes (List[str], optional): OAuth 2.0 scopes for authentication
22
        default_scopes (List[str], optional): Default scopes if none provided
23
        universe_domain (str, optional): Universe domain (default: googleapis.com)
24
    """
25
    def __init__(self, api_endpoint=None, client_cert_source=None, client_encrypted_cert_source=None, quota_project_id=None, credentials_file=None, scopes=None, default_scopes=None, universe_domain=None): ...
26
    
27
    @property
28
    def api_endpoint(self):
29
        """
30
        Custom API endpoint URL.
31
        
32
        Returns:
33
            str or None: API endpoint URL
34
        """
35
    
36
    @property
37
    def client_cert_source(self):
38
        """
39
        Function that returns client certificate for mTLS.
40
        
41
        Returns:
42
            Callable or None: Certificate source function
43
        """
44
    
45
    @property
46
    def client_encrypted_cert_source(self):
47
        """
48
        Function that returns encrypted client certificate.
49
        
50
        Returns:
51
            Callable or None: Encrypted certificate source function
52
        """
53
    
54
    @property
55
    def quota_project_id(self):
56
        """
57
        Project ID for quota and billing attribution.
58
        
59
        Returns:
60
            str or None: Project ID
61
        """
62
    
63
    @property
64
    def credentials_file(self):
65
        """
66
        Path to service account credentials file.
67
        
68
        Returns:
69
            str or None: Credentials file path
70
        """
71
    
72
    @property
73
    def scopes(self):
74
        """
75
        OAuth 2.0 scopes for authentication.
76
        
77
        Returns:
78
            List[str] or None: Authentication scopes
79
        """
80
    
81
    @property
82
    def universe_domain(self):
83
        """
84
        Universe domain for the service.
85
        
86
        Returns:
87
            str: Universe domain (default: googleapis.com)
88
        """
89

90
def from_dict(options):
91
    """
92
    Construct ClientOptions from a dictionary or mapping.
93
    
94
    Args:
95
        options (dict): Dictionary containing client option values
96
        
97
    Returns:
98
        ClientOptions: Constructed client options instance
99
    """
100
```
101

102
### Client Information
103

104
Client metadata for identifying library and version in API requests.
105

106
```python { .api }
107
class ClientInfo:
108
    """
109
    Client information for user-agent headers and telemetry.
110
    
111
    Args:
112
        client_library_name (str, optional): Name of the client library
113
        client_library_version (str, optional): Version of the client library
114
        application_name (str, optional): Name of the application using the client
115
        user_agent (str, optional): Custom user agent string
116
    """
117
    def __init__(self, client_library_name=None, client_library_version=None, application_name=None, user_agent=None): ...
118
    
119
    @property
120
    def client_library_name(self):
121
        """
122
        Name of the client library.
123
        
124
        Returns:
125
            str or None: Client library name
126
        """
127
    
128
    @property
129
    def client_library_version(self):
130
        """
131
        Version of the client library.
132
        
133
        Returns:
134
            str or None: Client library version
135
        """
136
    
137
    @property
138
    def application_name(self):
139
        """
140
        Name of the application using the client.
141
        
142
        Returns:
143
            str or None: Application name
144
        """
145
    
146
    @property
147
    def user_agent(self):
148
        """
149
        User agent string for HTTP requests.
150
        
151
        Returns:
152
            str: Complete user agent string
153
        """
154
    
155
    def to_grpc_metadata(self):
156
        """
157
        Convert client info to gRPC metadata format.
158
        
159
        Returns:
160
            List[Tuple[str, str]]: gRPC metadata pairs
161
        """
162
    
163
    def to_user_agent(self):
164
        """
165
        Generate user agent string from client info.
166
        
167
        Returns:
168
            str: User agent string for HTTP headers
169
        """
170
```
171

172
## Usage Examples
173

174
### Basic Client Configuration
175

176
```python
177
from google.api_core import client_options
178
from google.auth import default
179

180
# Create basic client options
181
options = client_options.ClientOptions(
182
    api_endpoint="https://custom-api.example.com",
183
    quota_project_id="my-billing-project"
184
)
185

186
# Use with a client library
187
from google.cloud import storage
188

189
client = storage.Client(client_options=options)
190
```
191

192
### mTLS Configuration
193

194
```python
195
from google.api_core import client_options
196
import ssl
197

198
def get_client_cert():
199
    """Load client certificate for mTLS."""
200
    with open("/path/to/client.crt", "rb") as cert_file:
201
        cert_data = cert_file.read()
202
    with open("/path/to/client.key", "rb") as key_file:
203
        key_data = key_file.read()
204
    return cert_data, key_data
205

206
# Configure mTLS
207
options = client_options.ClientOptions(
208
    api_endpoint="https://mtls-api.example.com",
209
    client_cert_source=get_client_cert
210
)
211

212
# Client will use mTLS for authentication
213
client = MyAPIClient(client_options=options)
214
```
215

216
### Configuration from Dictionary
217

218
```python
219
from google.api_core import client_options
220

221
# Configuration from dictionary
222
config_dict = {
223
    "api_endpoint": "https://europe-west1-api.example.com",
224
    "quota_project_id": "my-project-123",
225
    "scopes": [
226
        "https://www.googleapis.com/auth/cloud-platform",
227
        "https://www.googleapis.com/auth/bigquery"
228
    ],
229
    "universe_domain": "googleapis.com"
230
}
231

232
options = client_options.from_dict(config_dict)
233

234
# Use configured options
235
client = MyAPIClient(client_options=options)
236
```
237

238
### Client Information Setup
239

240
```python
241
from google.api_core import client_info
242

243
# Create client info for telemetry
244
info = client_info.ClientInfo(
245
    client_library_name="my-python-client",
246
    client_library_version="1.2.3",
247
    application_name="data-processor-app"
248
)
249

250
# Use with API client
251
client = MyAPIClient(client_info=info)
252

253
# Get user agent string
254
user_agent = info.to_user_agent()
255
print(user_agent)  # "my-python-client/1.2.3 data-processor-app"
256

257
# Get gRPC metadata
258
metadata = info.to_grpc_metadata()
259
print(metadata)  # [('x-goog-api-client', 'my-python-client/1.2.3')]
260
```
261

262
### Environment-Based Configuration
263

264
```python
265
import os
266
from google.api_core import client_options
267

268
def create_client_options_from_env():
269
    """Create client options from environment variables."""
270
    options = client_options.ClientOptions()
271
    
272
    # Set endpoint from environment
273
    if endpoint := os.getenv("API_ENDPOINT"):
274
        options = client_options.ClientOptions(api_endpoint=endpoint)
275
    
276
    # Set quota project from environment
277
    if project := os.getenv("QUOTA_PROJECT_ID"):
278
        options = client_options.ClientOptions(
279
            api_endpoint=options.api_endpoint,
280
            quota_project_id=project
281
        )
282
    
283
    # Set credentials file from environment
284
    if creds_file := os.getenv("GOOGLE_APPLICATION_CREDENTIALS"):
285
        options = client_options.ClientOptions(
286
            api_endpoint=options.api_endpoint,
287
            quota_project_id=options.quota_project_id,
288
            credentials_file=creds_file
289
        )
290
    
291
    return options
292

293
# Use environment-based configuration
294
options = create_client_options_from_env()
295
client = MyAPIClient(client_options=options)
296
```
297

298
### Regional Endpoint Configuration
299

300
```python
301
from google.api_core import client_options
302

303
def create_regional_client(region="us-central1"):
304
    """Create client configured for specific region."""
305
    # Regional endpoint pattern for Google Cloud APIs
306
    endpoint = f"https://{region}-api.example.com"
307
    
308
    options = client_options.ClientOptions(
309
        api_endpoint=endpoint,
310
        quota_project_id="my-regional-project"
311
    )
312
    
313
    return MyAPIClient(client_options=options)
314

315
# Create clients for different regions
316
us_client = create_regional_client("us-central1")
317
eu_client = create_regional_client("europe-west1") 
318
asia_client = create_regional_client("asia-southeast1")
319
```
320

321
### Advanced Configuration Pattern
322

323
```python
324
from google.api_core import client_options, client_info
325
from google.auth import default
326
import logging
327

328
class ConfiguredClient:
329
    """Example of a properly configured Google API client."""
330
    
331
    def __init__(self, service_name, version, **config):
332
        # Set up client info
333
        self.client_info = client_info.ClientInfo(
334
            client_library_name=f"{service_name}-python",
335
            client_library_version=version,
336
            application_name=config.get("app_name", "unknown-app")
337
        )
338
        
339
        # Set up client options
340
        self.client_options = client_options.ClientOptions(
341
            api_endpoint=config.get("endpoint"),
342
            quota_project_id=config.get("quota_project"),
343
            credentials_file=config.get("credentials_file"),
344
            universe_domain=config.get("universe_domain", "googleapis.com")
345
        )
346
        
347
        # Initialize credentials
348
        self.credentials, self.project = default(
349
            scopes=config.get("scopes"),
350
            quota_project_id=self.client_options.quota_project_id
351
        )
352
        
353
        # Configure logging
354
        self.logger = logging.getLogger(f"{service_name}.client")
355
        
356
    def get_config_summary(self):
357
        """Get summary of current configuration."""
358
        return {
359
            "endpoint": self.client_options.api_endpoint,
360
            "project": self.project,
361
            "quota_project": self.client_options.quota_project_id,
362
            "client_info": self.client_info.to_user_agent(),
363
            "universe_domain": self.client_options.universe_domain
364
        }
365

366
# Usage
367
config = {
368
    "endpoint": "https://api.example.com",
369
    "quota_project": "my-billing-project",
370
    "app_name": "data-pipeline",
371
    "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
372
}
373

374
configured_client = ConfiguredClient("myservice", "1.0.0", **config)
375
print("Client configuration:", configured_client.get_config_summary())
376
```
377

378
### Scope Management
379

380
```python
381
from google.api_core import client_options
382

383
# Define scopes for different access levels
384
READ_ONLY_SCOPES = [
385
    "https://www.googleapis.com/auth/cloud-platform.read-only"
386
]
387

388
FULL_ACCESS_SCOPES = [
389
    "https://www.googleapis.com/auth/cloud-platform"
390
]
391

392
SPECIFIC_SERVICE_SCOPES = [
393
    "https://www.googleapis.com/auth/bigquery",
394
    "https://www.googleapis.com/auth/storage.full_control"
395
]
396

397
def create_client_with_scopes(access_level="read-only"):
398
    """Create client with appropriate scopes based on access level."""
399
    scope_map = {
400
        "read-only": READ_ONLY_SCOPES,
401
        "full": FULL_ACCESS_SCOPES,
402
        "specific": SPECIFIC_SERVICE_SCOPES
403
    }
404
    
405
    scopes = scope_map.get(access_level, READ_ONLY_SCOPES)
406
    
407
    options = client_options.ClientOptions(
408
        scopes=scopes,
409
        quota_project_id="my-project"
410
    )
411
    
412
    return MyAPIClient(client_options=options)
413

414
# Create clients with different access levels
415
readonly_client = create_client_with_scopes("read-only")
416
full_client = create_client_with_scopes("full")
417
specific_client = create_client_with_scopes("specific")
418
```