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 de requête

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 du client de l'API sont transmises sans modification au service de backend. Il appartient 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 sans modification au client de l'API. Il appartient ensuite au client de l'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 suivante:

Backend	x-google-backend
Fonctions Cloud Run	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 ressource, compatible avec votre API. Vous pouvez spécifier un chemin d'accès absolu ou un chemin d'accès qui utilise des paramètres de chemin d'accès:

Chemin	Chemin avec paramètres
paths: /hello:	paths: /hello/{name}:

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

Lorsque API Gateway gère une requête du client de l'API, il prend l'URL de la requête envoyée par le client de l'API et la traduit en URL utilisée pour envoyer la requête au service de backend. La façon dont cette traduction se produit exactement dépend de la stratégie de traduction de chemin 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 backend utilisent APPEND_PATH_TO_ADDRESS, car cela signifie que le backend reçoit le même chemin de ressource que celui spécifié par le client de l'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 client contient un chemin de ressource, il 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 les fonctions Cloud Run.

Exemple :

• APPEND_PATH_TO_ADDRESS
  • address : https://PROJECT_ID.appspot.com
  • 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://PROJECT_ID.appspot.com/hello
  • Avec des 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 des 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 des opérations de la spécification OpenAPI, path_translation est défini par défaut sur CONSTANT_ADDRESS.