Transmettre des données vers et depuis le service de backend

Lorsqu'un client API envoie une requête à votre API déployée sur API Gateway, le client peut transmettre tout ou partie des informations suivantes dans le cadre de la requête :

• En-têtes de requête
• Paramètres de requête
• Données de formulaire
• Charges utiles XML ou JSON
• Chemins des requêtes

Lors de la création de sa réponse à la requête API, le service de backend peut renvoyer des données au client API, y compris :

• En-têtes de réponse
• Charges utiles XML ou JSON

Ce document décrit la manière dont ces données sont transmises vers et depuis le service de backend.

Comment les données de requête sont-elles transmises au service de backend ?

Toutes les données de la requête provenant du client API sont transmises telles quelles au service de backend. C'est ensuite au service de backend d'analyser les données de la requête dans le cadre de son traitement.

Comment les données de réponse sont-elles renvoyées au client de l'API ?

Toutes les données reçues dans la réponse du service de backend sont transmises telles quelles au client API. Il revient ensuite au client API de traiter les données renvoyées dans la réponse.

Comment l'URL de requête est-elle transmise au service de backend ?

L'URL utilisée pour envoyer une requête au service de backend est contrôlée par l'extension x-google-backend. Cette section décrit les options de configuration de l'URL du service de backend.

Définir l'adresse et le chemin d'accès du service de backend dans la spécification OpenAPI

Dans la spécification OpenAPI que vous utilisez pour créer une configuration d'API, vous utilisez l'extension x-google-backend pour spécifier l'URL du service de backend. Par exemple, vous spécifiez le service de backend sous la forme:

Backend	x-google-backend
Cloud Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://hello-HASH.a.run.app
Environnement standard App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

Dans ces exemples :

1. GCP_REGION spécifie la région GCP du backend déployé.
2. PROJECT_ID spécifie l'ID du projet Google Cloud.
3. HASH spécifie le code de hachage unique généré lors de la création du service Cloud Run.

De plus, le paramètre path de la spécification OpenAPI spécifie le point de terminaison (ou resource) compatible avec votre API. Vous pouvez spécifier un chemin absolu ou utilisant des paramètres de chemin d'accès:

Chemin	Chemin d'accès avec paramètres
paths: /hello:	paths: /hello/{name}:

Générer l'URL du service de backend à partir d'une requête API

Lorsqu'API Gateway traite une requête du client API, elle prend l'URL de requête envoyée par le client API et la convertit en URL utilisée pour envoyer la requête au service de backend. La façon dont cette traduction se produit dépend de la stratégie de traduction du chemin d'accès que vous utilisez.

L'option path_translation de l'extension x-google-backend accepte deux stratégies de traduction de chemin d'accès :

• APPEND_PATH_TO_ADDRESS : l'URL du service de backend est générée en ajoutant le chemin d'accès à la ressource de la requête du client à l'URL address de l'extension x-google-backend.

  La plupart des services de backend utilisent APPEND_PATH_TO_ADDRESS, car cela signifie que le backend reçoit le même chemin d'accès aux ressources que celui spécifié par le client API.

• CONSTANT_ADDRESS: l'URL du service de backend est constante, comme défini par l'URL address de l'extension x-google-backend. Si la requête du client contient un chemin d'accès à la ressource, celui-ci est ajouté à l'URL du service de backend à l'aide de paramètres de requête.

  Cette méthode est généralement utilisée par Cloud Functions.

Exemple :

• APPEND_PATH_TO_ADDRESS
  • address : https://PROJECT_ID.appspot.com
  • Sans les paramètres de chemin OpenAPI :
    • Chemin OpenAPI : /hello
    • Chemin d'accès à la ressource de requête du client API : /hello
    • URL de la requête du service de backend : https://PROJECT_ID.appspot.com/hello
  • Avec les paramètres de chemin OpenAPI :
    • Chemin OpenAPI : /hello/{name}
    • Chemin d'accès à la ressource de requête du client API : /hello/Dave
    • URL de la requête du service de backend : https://PROJECT_ID.appspot.com/hello/Dave
• CONSTANT_ADDRESS
  • address : https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Sans paramètres de chemin OpenAPI
    • Chemin OpenAPI : /hello
    • Chemin d'accès à la ressource de requête du client API : /hello
    • URL de la requête du service de backend : https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Avec les paramètres de chemin OpenAPI
    • Chemin OpenAPI : /hello/{name}
    • Chemin d'accès à la ressource de requête du client API : /hello/Dave
    • URL de la requête du service de backend : https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Configurer path_translation

Définissez path_translation dans le cadre de la définition de x-google-backend :

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]`

La valeur par défaut path_translation dépend de l'emplacement où vous avez défini x-google-backend dans votre spécification OpenAPI :

• Lorsque x-google-backend est utilisé au niveau supérieur de la spécification OpenAPI, path_translation est défini par défaut sur APPEND_PATH_TO_ADDRESS.

• Lorsque x-google-backend est utilisé au niveau de l'opération de la spécification OpenAPI, path_translation est défini par défaut sur CONSTANT_ADDRESS.