Transferir dados para e a partir do serviço de back-end

Quando um cliente API faz um pedido à sua API implementada no API Gateway, o cliente pode transmitir algumas ou todas as seguintes informações como parte do pedido:

• Cabeçalhos do pedido
• Parâmetros de consulta
• Dados do formulário
• Payloads XML ou JSON
• Caminhos de pedidos

Ao criar a respetiva resposta ao pedido da API, o serviço de back-end pode devolver dados ao cliente da API, incluindo:

• Cabeçalhos das respostas
• Payloads XML ou JSON

Este documento descreve como estes dados são transmitidos para e a partir do serviço de back-end.

Como são transmitidos os dados de pedidos ao serviço de back-end?

Todos os dados no pedido do cliente da API são transmitidos inalterados para o serviço de back-end. Em seguida, cabe ao serviço de back-end analisar os dados do pedido como parte do processamento do pedido.

Como é que os dados de resposta são devolvidos ao cliente API?

Todos os dados recebidos na resposta do serviço de back-end são transmitidos inalterados ao cliente da API. Em seguida, cabe ao cliente API processar todos os dados devolvidos na resposta.

Como é que o URL do pedido é transmitido ao serviço de back-end?

O URL usado para fazer um pedido ao serviço de back-end é controlado pela extensão x-google-backend. Esta secção descreve as opções de configuração do URL do serviço de back-end.

Definir o endereço e o caminho do serviço de back-end na especificação OpenAPI

Na especificação OpenAPI que usa para criar uma configuração da API, usa a extensão x-google-backend para especificar o URL do serviço de back-end. Por exemplo, especifica o serviço de back-end no formulário:

Back-end	x-google-backend
Funções do 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
Ambiente padrão do App Engine	x-google-backend: address: https://PROJECT_ID.appspot.com

Nestes exemplos:

1. GCP_REGION especifica a Google Cloud região para o back-end implementado.
2. PROJECT_ID especifica o Google Cloud ID do projeto.
3. HASH especifica o código hash exclusivo gerado quando o serviço do Cloud Run é criado.

Além disso, o parâmetro path na especificação OpenAPI especifica o ponto final ou o recurso, suportado pela sua API. Pode especificar um caminho absoluto ou um que use parâmetros de caminho:

Caminho	Caminho com parâmetros
paths: /hello:	paths: /hello/{name}:

Gerar o URL do serviço de back-end a partir de um pedido de API

À medida que o API Gateway processa um pedido do cliente API, recebe o URL do pedido enviado pelo cliente API e traduz o URL no URL usado para fazer o pedido ao serviço de back-end. A forma exata como esta tradução ocorre depende da estratégia de tradução de caminhos que está a usar.

A opção path_translation para a extensão x-google-backend suporta duas estratégias de tradução de caminhos:

• APPEND_PATH_TO_ADDRESS: o URL do serviço de back-end é gerado anexando o caminho do recurso do pedido do cliente ao URL address da extensão x-google-backend.

  A maioria dos serviços de back-end usa APPEND_PATH_TO_ADDRESS porque significa que o back-end recebe o mesmo caminho de recurso especificado pelo cliente API.

• CONSTANT_ADDRESS: o URL do serviço de back-end é constante, conforme definido pelo URL address da extensão x-google-backend. Se o pedido do cliente contiver um caminho do recurso, o caminho do recurso é adicionado ao URL do serviço de back-end através de parâmetros de consulta.

  Normalmente, este método é usado por funções do Cloud Run.

Por exemplo:

• APPEND_PATH_TO_ADDRESS
  • address: https://PROJECT_ID.appspot.com
  • Sem parâmetros de caminho do OpenAPI:
    • Caminho da OpenAPI: /hello
    • Caminho do recurso do pedido do cliente API: /hello
    • URL do pedido do serviço de back-end: https://PROJECT_ID.appspot.com/hello
  • Com parâmetros de caminho da OpenAPI:
    • Caminho da OpenAPI: /hello/{name}
    • Caminho do recurso do pedido do cliente API: /hello/Dave
    • URL do pedido do serviço de back-end: https://PROJECT_ID.appspot.com/hello/Dave
• CONSTANT_ADDRESS
  • address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Sem parâmetros de caminho OpenAPI
    • Caminho da OpenAPI: /hello
    • Caminho do recurso do pedido do cliente API: /hello
    • URL do pedido do serviço de back-end: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello
  • Com parâmetros de caminho da OpenAPI
    • Caminho da OpenAPI: /hello/{name}
    • Caminho do recurso do pedido do cliente API: /hello/Dave
    • URL do pedido do serviço de back-end: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

A definir path_translation

Defina path_translation como parte da definição de x-google-backend:

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

O valor predefinido de path_translation depende de onde define x-google-backend na especificação da API OpenAPI:

• Quando x-google-backend é usado no nível superior da especificação OpenAPI, o valor predefinido de path_translation é APPEND_PATH_TO_ADDRESS.

• Quando x-google-backend é usado ao nível da operação da especificação OpenAPI, path_translation tem como predefinição CONSTANT_ADDRESS.