0
# Transport Adapters
1
2
HTTP transport implementations for making authenticated requests across different HTTP libraries. Transport adapters handle credential application, automatic refresh, and provide consistent interfaces across different HTTP client implementations.
3
4
## Capabilities
5
6
### Requests Transport
7
8
HTTP transport using the popular `requests` library, providing session management and automatic credential refresh.
9
10
```python { .api }
11
class Request(google.auth.transport.Request):
12
"""Requests-based HTTP transport for credential refresh."""
13
14
def __init__(self, session=None):
15
"""
16
Initialize the transport.
17
18
Args:
19
session (requests.Session): The requests session to use.
20
If not specified, a new session will be created.
21
"""
22
23
def __call__(self, method, url, data=None, headers=None, **kwargs):
24
"""
25
Make an HTTP request.
26
27
Args:
28
method (str): The HTTP method (GET, POST, etc.)
29
url (str): The URL to request
30
data (bytes): Request body data
31
headers (Mapping[str, str]): Request headers
32
**kwargs: Additional arguments to pass to requests
33
34
Returns:
35
google.auth.transport.Response: The HTTP response
36
"""
37
38
class AuthorizedSession(requests.Session):
39
"""Requests session with automatic credential refresh."""
40
41
def __init__(self, credentials, refresh_status_codes=None, max_refresh_attempts=None):
42
"""
43
Initialize an authorized session.
44
45
Args:
46
credentials (google.auth.credentials.Credentials): The credentials to use
47
refresh_status_codes (Sequence[int]): HTTP status codes that trigger refresh
48
max_refresh_attempts (int): Maximum number of refresh attempts
49
"""
50
51
def request(self, method, url, **kwargs):
52
"""
53
Make an authenticated HTTP request.
54
55
Args:
56
method (str): HTTP method
57
url (str): URL to request
58
**kwargs: Additional arguments to pass to requests
59
60
Returns:
61
requests.Response: The HTTP response
62
"""
63
```
64
65
Usage example:
66
67
```python
68
import google.auth
69
from google.auth.transport import requests
70
71
# Get default credentials
72
credentials, project = google.auth.default()
73
74
# Create authenticated session
75
authed_session = requests.AuthorizedSession(credentials)
76
77
# Make authenticated requests
78
response = authed_session.get('https://www.googleapis.com/compute/v1/projects')
79
print(response.json())
80
81
# Use with different HTTP methods
82
response = authed_session.post(
83
'https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances',
84
json={'name': 'test-instance', 'machineType': 'e2-micro'}
85
)
86
```
87
88
### urllib3 Transport
89
90
HTTP transport using `urllib3`, useful for environments where `requests` is not available or for lower-level HTTP control.
91
92
```python { .api }
93
class Request(google.auth.transport.Request):
94
"""urllib3-based HTTP transport."""
95
96
def __init__(self, http=None):
97
"""
98
Initialize the transport.
99
100
Args:
101
http (urllib3.PoolManager): The urllib3 HTTP client.
102
If not specified, a new PoolManager will be created.
103
"""
104
105
class AuthorizedHttp:
106
"""urllib3 HTTP client with automatic credential refresh."""
107
108
def __init__(self, credentials, http=None, refresh_status_codes=None, max_refresh_attempts=None):
109
"""
110
Initialize an authorized HTTP client.
111
112
Args:
113
credentials (google.auth.credentials.Credentials): The credentials to use
114
http (urllib3.PoolManager): The urllib3 client
115
refresh_status_codes (Sequence[int]): Status codes that trigger refresh
116
max_refresh_attempts (int): Maximum refresh attempts
117
"""
118
119
def request(self, method, url, **kwargs):
120
"""
121
Make an authenticated HTTP request.
122
123
Args:
124
method (str): HTTP method
125
url (str): URL to request
126
**kwargs: Additional arguments to pass to urllib3
127
128
Returns:
129
urllib3.HTTPResponse: The HTTP response
130
"""
131
```
132
133
Usage example:
134
135
```python
136
import google.auth
137
from google.auth.transport import urllib3
138
139
# Get credentials
140
credentials, project = google.auth.default()
141
142
# Create authenticated HTTP client
143
http = urllib3.AuthorizedHttp(credentials)
144
145
# Make requests
146
response = http.request('GET', 'https://www.googleapis.com/compute/v1/projects')
147
```
148
149
### gRPC Transport
150
151
Transport adapter for gRPC-based Google APIs, providing automatic credential refresh and secure channel creation.
152
153
```python { .api }
154
def secure_authorized_channel(
155
credentials,
156
request,
157
target,
158
ssl_credentials=None,
159
client_cert_callback=None,
160
**kwargs
161
):
162
"""
163
Create a secure authorized gRPC channel.
164
165
Args:
166
credentials (google.auth.credentials.Credentials): The credentials to use
167
request (google.auth.transport.Request): HTTP transport for credential refresh
168
target (str): The gRPC server address
169
ssl_credentials (grpc.ChannelCredentials): SSL credentials for the channel
170
client_cert_callback (Callable): Callback for client certificate
171
**kwargs: Additional arguments to pass to grpc.secure_channel
172
173
Returns:
174
grpc.Channel: The secure gRPC channel
175
"""
176
177
class AuthMetadataPlugin(grpc.AuthMetadataPlugin):
178
"""gRPC authentication metadata plugin."""
179
180
def __init__(self, credentials, request):
181
"""
182
Initialize the plugin.
183
184
Args:
185
credentials (google.auth.credentials.Credentials): The credentials to use
186
request (google.auth.transport.Request): HTTP transport for refresh
187
"""
188
189
def __call__(self, context, callback):
190
"""
191
Get authentication metadata for gRPC call.
192
193
Args:
194
context (grpc.AuthMetadataContext): The gRPC auth context
195
callback (grpc.AuthMetadataPluginCallback): Callback for metadata
196
"""
197
```
198
199
Usage example:
200
201
```python
202
import google.auth
203
from google.auth.transport import grpc, requests
204
205
# Get credentials
206
credentials, project = google.auth.default(
207
scopes=['https://www.googleapis.com/auth/cloud-platform']
208
)
209
210
# Create request object for credential refresh
211
request = requests.Request()
212
213
# Create secure authorized channel
214
channel = grpc.secure_authorized_channel(
215
credentials,
216
request,
217
'compute.googleapis.com:443'
218
)
219
220
# Use channel with gRPC stubs
221
# stub = compute_pb2_grpc.InstancesStub(channel)
222
```
223
224
### Async Transport (aiohttp)
225
226
Asynchronous HTTP transport using `aiohttp` for non-blocking credential refresh and requests.
227
228
```python { .api }
229
class Request(google.auth.transport.Request):
230
"""Async HTTP transport using aiohttp."""
231
232
def __init__(self, session=None):
233
"""
234
Initialize async transport.
235
236
Args:
237
session (aiohttp.ClientSession): The aiohttp session.
238
If not specified, a new session will be created.
239
"""
240
241
async def __call__(self, method, url, data=None, headers=None, **kwargs):
242
"""
243
Make an async HTTP request.
244
245
Args:
246
method (str): HTTP method
247
url (str): URL to request
248
data (bytes): Request body
249
headers (Mapping[str, str]): Request headers
250
**kwargs: Additional arguments
251
252
Returns:
253
google.auth.transport.Response: The HTTP response
254
"""
255
256
class AuthorizedSession(aiohttp.ClientSession):
257
"""Async session with automatic credential refresh."""
258
259
def __init__(self, credentials, **kwargs):
260
"""
261
Initialize async authorized session.
262
263
Args:
264
credentials (google.auth.credentials.Credentials): The credentials
265
**kwargs: Additional arguments to pass to aiohttp.ClientSession
266
"""
267
268
async def request(self, method, url, **kwargs):
269
"""
270
Make an async authenticated request.
271
272
Args:
273
method (str): HTTP method
274
url (str): URL to request
275
**kwargs: Additional arguments
276
277
Returns:
278
aiohttp.ClientResponse: The HTTP response
279
"""
280
```
281
282
Usage example:
283
284
```python
285
import asyncio
286
import google.auth
287
from google.auth.aio.transport import aiohttp
288
289
async def main():
290
# Get credentials
291
credentials, project = google.auth.default()
292
293
# Create async authorized session
294
async with aiohttp.AuthorizedSession(credentials) as session:
295
# Make async requests
296
async with session.get('https://www.googleapis.com/compute/v1/projects') as response:
297
data = await response.json()
298
print(data)
299
300
# Run async function
301
asyncio.run(main())
302
```
303
304
## Transport Interface
305
306
```python { .api }
307
class Request(abc.ABC):
308
"""Abstract base class for HTTP transport."""
309
310
@abc.abstractmethod
311
def __call__(self, method, url, data=None, headers=None, **kwargs):
312
"""
313
Make an HTTP request.
314
315
Args:
316
method (str): HTTP method
317
url (str): URL to request
318
data (bytes): Request body
319
headers (Mapping[str, str]): Request headers
320
321
Returns:
322
Response: HTTP response object
323
"""
324
325
class Response:
326
"""HTTP response object."""
327
328
@property
329
def status(self):
330
"""int: HTTP status code."""
331
332
@property
333
def headers(self):
334
"""Mapping[str, str]: Response headers."""
335
336
@property
337
def data(self):
338
"""bytes: Response body."""
339
```
340
341
## Error Handling
342
343
```python { .api }
344
class TransportError(google.auth.exceptions.GoogleAuthError):
345
"""Raised when transport encounters an error."""
346
347
class RefreshError(google.auth.exceptions.GoogleAuthError):
348
"""Raised when credential refresh fails during transport."""
349
```
350
351
Common transport error scenarios:
352
- Network connectivity issues
353
- HTTP transport configuration errors
354
- SSL/TLS certificate validation failures
355
- Credential refresh failures during request
356
- Timeout errors during authentication
357
- Invalid or malformed request/response data