Como transferir dados para e do serviço de back-end

Quando um cliente de API faz uma solicitação à API implantada no gateway de API, ele pode passar qualquer uma ou todas as informações abaixo como parte da solicitação:

  • Cabeçalhos de solicitação
  • Parâmetros de consulta
  • Dados do formulário
  • Payloads XML ou JSON
  • Caminhos de solicitação

Ao criar a resposta à solicitação de API, o serviço de back-end pode retornar dados ao cliente de API, incluindo:

  • Cabeçalhos de resposta
  • Payloads XML ou JSON

Neste documento, você verá como esses dados são transmitidos para e do serviço de back-end.

Como os dados da solicitação são transmitidos para o servidor de back-end?

Todos os dados da solicitação do cliente da API são transmitidos sem alterações para o serviço de back-end. Cabe ao serviço de back-end analisar os dados da solicitação como parte do processamento da solicitação.

Como os dados de resposta são retornados ao cliente da API?

Todos os dados recebidos na resposta do serviço de back-end são transmitidos inalterados para o cliente da API. Cabe ao cliente da API processar todos os dados retornados na resposta.

Como o URL de solicitação é transmitido ao serviço de back-end?

O URL usado para fazer uma solicitação ao serviço de back-end é controlado pela extensão x-google-backend. Esta seção descreve as opções para configurar o URL do serviço de back-end.

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

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

Back-end 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
Ambiente padrão do App Engine 

x-google-backend:
  address: https://PROJECT_ID.appspot.com

Nestes exemplos:

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

Além disso, o parâmetro path na especificação OpenAPI especifica o endpoint, ou recurso, compatível com sua API. É possível especificar um caminho absoluto ou um que use parâmetros de caminho:

Caminho Caminho com parâmetros 

paths:
  /hello:
 

paths:
  /hello/{name}:

Como gerar o URL do serviço de back-end a partir de uma solicitação de API

Como o gateway de API processa uma solicitação do cliente da API, ele pega o URL de solicitação enviado pelo cliente de API e o converte no URL usado para fazer a solicitação ao serviço de back-end. Como isso acontece exatamente depende da estratégia de conversão de caminho sendo usada.

A opção path_translation para a extensão x-google-backend é compatível com duas estratégias de conversão de caminho:

  • APPEND_PATH_TO_ADDRESS: o URL do serviço de back-end é gerado anexando o caminho do recurso da solicitação 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 da API.

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

    Esse método é normalmente usado pelo Cloud Functions.

Exemplo:

  • APPEND_PATH_TO_ADDRESS
    • address: https://PROJECT_ID.appspot.com
    • Sem parâmetros de caminho da OpenAPI:
      • Caminho da OpenAPI: /hello
      • Caminho do recurso da solicitação do cliente da API: /hello
      • URL da solicitação 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 da solicitação do cliente da API: /hello/Dave
      • URL da solicitação 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 da OpenAPI
      • Caminho da OpenAPI: /hello
      • Caminho do recurso da solicitação do cliente da API: /hello
      • URL da solicitação 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 da solicitação do cliente da API: /hello/Dave
      • URL da solicitação do serviço de back-end: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello?name=Dave

Como definir path_translation

Defina path_translation como parte da configuração 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 padrão de path_translation depende de onde você define x-google-backend na especificação OpenAPI:

  • Quando x-google-backend é usado no nível superior da especificação OpenAPI, path_translation assume APPEND_PATH_TO_ADDRESS como padrão.

  • Quando x-google-backend é usado no nível de operação da especificação OpenAPI, path_translation assume CONSTANT_ADDRESS como padrão.