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 incombe ensuite au service de backend d'analyser les données de la requête lors 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 incombe 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
Cloud Run Functions	x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
Cloud Run	x-google-backend: address: https://[TAG---]SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
Environnement standard App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

Dans ces exemples :

• GCP_REGION spécifie la région Google Cloud du backend déployé.
• PROJECT_ID spécifie l'ID de projet Google Cloud .
• TAG est le tag de trafic facultatif pour la révision Cloud Run que vous demandez. Consultez également URL déterministe dans la documentation Cloud Run.
• SERVICE_NAME correspond au nom du service Cloud Run.
• PROJECT_NUMBER est le numéro de projet Google Cloud .
• REGION est le nom de la région, par exemple us-west1.

De plus, le paramètre path de la spécification OpenAPI indique 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 utilisant 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

Lorsqu'API Gateway traite une requête du client d'API, il prend l'URL de la requête envoyée par le client d'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 des chemins 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 de ressource que celui spécifié par le client de l'API.

• CONSTANT_ADDRESS : l'URL du service de backend est constante, telle que définie par l'URL address de l'extension x-google-backend. Si la requête du client contient un chemin d'accès à une 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 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.