Bibliothèques clientes Python
Les API Google Cloud s'appellent en Python par les Cloud Client Libraries, un paquet google-cloud-* par service. La plupart sont générées à partir des définitions protobuf de l'API (générateur GAPIC) et partagent la même structure : un client par service, des méthodes qui prennent une requête, des pagers pour les listes et des objets Operation pour les traitements longs. Les exemples suivent google-api-core 2.38 et les versions de septembre 2026 ; Python 3.10 au minimum. L'authentification est traitée dans Authentifier un appel à une API, les erreurs et les relances dans Erreurs, quotas et relances, Gemini dans Appeler Gemini depuis du code.
Deux familles de bibliothèques
| Cloud Client Libraries | Google API Client Library | |
|---|---|---|
| Paquet | google-cloud-storage, google-cloud-secret-manager... |
google-api-python-client (un seul paquet) |
| Import | from google.cloud import secretmanager |
from googleapiclient.discovery import build |
| Construction | Générée par API, types protobuf (proto-plus) | Générique, construite depuis le document de découverte de l'API ; dictionnaires JSON |
| Protocole | gRPC ou REST selon la bibliothèque | REST seulement |
| État | Recommandée pour tout code neuf | Maintenance : corrections critiques seulement |
| Quand l'utiliser | Dès qu'un paquet google-cloud-* existe pour l'API |
API Google Workspace (Drive, Sheets, Admin SDK, Gmail) ; API Cloud dont le paquet manque ou reste en 0.x (Cloud SQL Admin : build("sqladmin", "v1beta4")) |
Google recommande les Cloud Client Libraries partout où elles existent (Client libraries explained). Une bibliothèque en version 0.x est en preview : son interface peut changer d'une version mineure à l'autre. La liste des API servies par le client de découverte est dans son index des API. Sans bibliothèque du tout, voir Appeler une API REST sans bibliothèque.
Paquets des services courants
| Service | Paquet pip | Import | Remarque |
|---|---|---|---|
| Cloud Storage | google-cloud-storage |
from google.cloud import storage |
Écrite à la main, JSON sur HTTP ; voir Storage et BigQuery |
| BigQuery | google-cloud-bigquery, google-cloud-bigquery-storage |
from google.cloud import bigquery |
REST pour les jobs ; lecture massive par la Storage Read API en gRPC |
| Pub/Sub | google-cloud-pubsub |
from google.cloud import pubsub_v1 |
Surcouche GAPIC : mise en lots à la publication, flux à l'abonnement |
| Firestore | google-cloud-firestore |
from google.cloud import firestore |
Voir Pub/Sub, Firestore, secrets |
| Secret Manager | google-cloud-secret-manager |
from google.cloud import secretmanager |
GAPIC pur ; sert d'exemple ci-dessous |
| Cloud Tasks | google-cloud-tasks |
from google.cloud import tasks_v2 |
|
| Cloud Run (administration) | google-cloud-run |
from google.cloud import run_v2 |
Encore en 0.x |
| Compute Engine | google-cloud-compute |
from google.cloud import compute_v1 |
REST seulement ; opérations ExtendedOperation |
| Cloud Logging | google-cloud-logging |
import google.cloud.logging |
Client().setup_logging() branche le module logging |
| Resource Manager | google-cloud-resource-manager |
from google.cloud import resourcemanager_v3 |
Projets, dossiers, tags |
| API ML | google-cloud-speech, -vision, -translate... |
speech_v2, vision, translate_v3 |
Voir Speech-to-Text et Text-to-Speech |
| Gemini | google-genai |
from google import genai |
SDK distinct ; voir SDK google-genai |
Installer et figer. Un fichier requirements.txt borne chaque paquet sur sa version majeure (google-cloud-secret-manager>=2.30,<3) et un fichier de verrouillage (pip-compile, uv lock) fixe les versions exactes, protobuf et grpcio compris : ce sont eux qui entrent en conflit quand plusieurs bibliothèques se côtoient. Il n'existe pas de nomenclature commune (BOM) côté Python.
Construire un client
from google.api_core.client_options import ClientOptions
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient() # ADC, point de terminaison mondial
regional = secretmanager.SecretManagerServiceClient(transport="rest", client_options=ClientOptions(
api_endpoint="secretmanager.europe-west1.rep.googleapis.com", # point de terminaison régional
quota_project_id="PROJECT_ID", # projet facturé pour les quotas
))
| Paramètre | Rôle |
|---|---|
credentials= |
Identifiants explicites ; par défaut ADC |
transport= |
"grpc" (défaut des clients GAPIC), "rest", "grpc_asyncio" pour le client asynchrone |
client_options.api_endpoint |
Autre hôte : régional (SERVICE.REGION.rep.googleapis.com), Private Service Connect, émulateur |
client_options.quota_project_id |
Projet de quota, envoyé en en-tête x-goog-user-project |
client_options.universe_domain |
Univers autre que googleapis.com (cloud souverain) ; aussi GOOGLE_CLOUD_UNIVERSE_DOMAIN |
client_options.api_key |
Clé API, pour les rares API qui l'acceptent |
Les bibliothèques écrites à la main (storage.Client, bigquery.Client, firestore.Client) prennent en plus project= ; BigQuery prend location=. Un point de terminaison régional garantit que la requête est traitée dans la région ; les régions disponibles sont listées dans la documentation du service et dans le champ endpoints de son document de découverte.
gRPC ou REST. gRPC (protobuf sur HTTP/2) est le plus efficace et le seul à porter les flux bidirectionnels. REST passe là où gRPC bloque : proxy d'entreprise qui ne laisse pas passer HTTP/2, environnement où grpcio s'installe mal, image minimale, ou fork sans précaution. Le client asynchrone ne dispose en général que de grpc_asyncio.
Appeler une méthode
Chaque méthode accepte soit un objet requête (ou un dictionnaire), soit les paramètres aplatis les plus courants, jamais les deux à la fois (ValueError). Les chemins de ressource se construisent par des méthodes de classe.
from google.api_core import retry
nom = client.secret_version_path("PROJECT_ID", "db-password", "latest")
valeur = client.access_secret_version(name=nom, timeout=10).payload.data.decode()
# Objet requête : tous les champs, dont ceux absents des paramètres aplatis
pager = client.list_secrets(request={"parent": "projects/PROJECT_ID", "page_size": 100, "filter": "labels.env=prod"})
# Masque de champs : seuls les champs nommés sont modifiés
client.update_secret(
secret={"name": client.secret_path("PROJECT_ID", "db-password"), "labels": {"env": "prod"}},
update_mask={"paths": ["labels"]},
retry=retry.Retry(initial=1.0, maximum=30.0, timeout=120.0),
)
timeout, en secondes, borne la durée totale de l'appel, relances comprises ; retry remplace la politique de relance par défaut de la méthode. Chaque version d'API a son module : secretmanager est l'alias du module stable secretmanager_v1, les fonctions en preview sont dans secretmanager_v1beta2, qu'on importe explicitement. Pour certains services, deux versions stables coexistent (speech et speech_v2) et n'ont pas les mêmes méthodes.
Pagination
Une méthode list_* renvoie un pager : itérer dessus parcourt les éléments et appelle les pages suivantes au fil de l'eau. .pages donne les réponses brutes, page par page ; page_size fixe la taille demandée, que le serveur peut réduire.
for secret in client.list_secrets(parent="projects/PROJECT_ID"):
print(secret.name)
for page in client.list_secrets(request={"parent": "projects/PROJECT_ID", "page_size": 500}).pages:
traiter_lot(page.secrets)
Les bibliothèques écrites à la main suivent le même principe : storage.Client.list_blobs(..., page_size=) et bigquery.Client.list_rows(..., page_size=) renvoient des itérateurs dotés de .pages.
Client asynchrone. Chaque client GAPIC a son pendant ...AsyncClient, aux mêmes méthodes en coroutines ; le pager s'obtient par await puis se parcourt par async for.
async def noms_des_secrets():
async with secretmanager.SecretManagerServiceAsyncClient() as client:
return [s.name async for s in await client.list_secrets(parent="projects/PROJECT_ID")]
Opérations longues
Une méthode qui crée ou modifie une ressource lourde renvoie un google.api_core.operation.Operation au lieu du résultat.
from google.cloud import run_v2
services = run_v2.ServicesClient()
operation = services.create_service(
parent="projects/PROJECT_ID/locations/REGION",
service_id="api",
service=run_v2.Service(template=run_v2.RevisionTemplate(containers=[run_v2.Container(image="IMAGE")])),
)
print(operation.operation.name) # nom de l'opération, à journaliser pour la reprendre
service = operation.result(timeout=600) # attend, lève l'erreur de l'opération si elle échoue
| Méthode | Effet |
|---|---|
result(timeout=) |
Interroge le serveur jusqu'à la fin, renvoie la réponse typée ; TimeoutError passé le délai, sans annuler l'opération |
done(), metadata, cancel() |
Sonde sans bloquer ; metadata porte l'avancement quand l'API en publie ; l'annulation n'est pas honorée par toutes les API |
add_done_callback(fn) |
Rappel à la fin, exécuté dans un fil séparé |
google-cloud-compute renvoie un ExtendedOperation : même result(), qui lève l'erreur à la fin, et en plus error_code et error_message pour lire un échec sans exception.
Réutilisation, journaux, traces
- Un client par processus, créé au démarrage et réutilisé : chaque instance ouvre son canal gRPC ou son pool HTTP et récupère ses jetons. Les clients gRPC se partagent entre fils d'exécution.
- Après
fork: gRPC ne supporte pas qu'un canal ouvert traverseos.fork(). Avecmultiprocessing, Gunicorn en preload ou Celery, créer les clients dans chaque processus enfant, après lefork(Multiprocessing). - Journaux de débogage :
GOOGLE_SDK_PYTHON_LOGGING_SCOPE=google(ougoogle.cloud.secretmanager_v1) émet requêtes et réponses en journal structuré, sans modifier le code. Pour le transport lui-même :GRPC_VERBOSITY=debugetGRPC_TRACE=http,call_error. Ces journaux contiennent des données de la requête : ne pas les laisser actifs en production. - OpenTelemetry : BigQuery produit des spans dès que
opentelemetry-apiest installé ; Pub/Sub sur option (PublisherOptions(enable_open_telemetry_tracing=True)) ; Cloud Storage avecENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=true. Pour les clients GAPIC, le traçage par méthode est expérimental (GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED=true,ClientOptions(tracer_provider=...)) ; l'instrumentation génériqueopentelemetry-instrumentation-grpcou-requestscouvre tous les clients.
Pièges
- Client créé à chaque requête. Dans une fonction Cloud Run, le créer au niveau du module, pas dans le gestionnaire : sinon chaque appel paie l'ouverture du canal et l'obtention d'un jeton.
request=et paramètres aplatis mêlés.list_secrets(request={...}, parent=...)lèveValueError. Choisir l'une des deux formes.- Liste tronquée. Lire seulement
pager.secretsou la première page de.pagesne renvoie qu'une page. Itérer sur le pager lui-même. - Masque oublié. Selon l'API, une méthode
update_*sansupdate_maskest refusée (Secret Manager l'exige) ou applique tous les champs renseignés de l'objet envoyé. Toujours nommer les champs modifiés. result()sans délai. Sanstimeout,operation.result()suit la politique de sondage par défaut (900 secondes dansgoogle-api-core, sauf réglage propre à la méthode), trop courte pour une création lourde ou trop longue pour une requête web. Fixer un délai adapté et journaliseroperation.operation.name.- Point de terminaison et ressource incohérents. Un secret régional (
projects/PROJECT_ID/locations/REGION/secrets/...) ne se lit que par le point de terminaison de sa région ; l'hôte mondial renvoie une erreur.