Esta página foi traduzida pela API Cloud Translation.

Extensões OpenAPI

OpenAPI | gRPC

O Cloud Endpoints aceita um conjunto de extensões específicas da Google à especificação OpenAPI que configuram os comportamentos do proxy de serviço extensível (ESP), do proxy de serviço extensível V2 (ESPv2) e do controlo de serviços. Esta página descreve as extensões específicas da Google à especificação OpenAPI.

Embora os exemplos apresentados abaixo estejam no formato YAML, o formato JSON também é suportado.

Convenção de nomenclatura

As extensões da API Google OpenAPI têm nomes que começam com o prefixo x-google-.

`x-google-allow`

x-google-allow: [configured | all]

Esta extensão é usada no nível superior de uma especificação OpenAPI para indicar que caminhos de URL devem ser permitidos através do ESP.

Os valores possíveis são configured e all.

O valor predefinido é configured, o que significa que apenas os métodos da API que listou na sua especificação OpenAPI são publicados através do ESP.

Quando o all é usado, as chamadas não configuradas, com ou sem uma chave de API ou autenticação do utilizador, passam pelo ESP para a sua API.

O ESP processa as chamadas para a sua API de forma sensível a maiúsculas e minúsculas. Por exemplo, o ESP considera /widgets e /Widgets como métodos de API diferentes.

Quando usa a funcionalidade all, tem de ter cuidado adicional em duas áreas:

Qualquer chave da API ou regras de autenticação.
O encaminhamento do caminho de back-end no seu serviço.

Como prática recomendada, sugerimos que configure a sua API para usar o encaminhamento de caminhos sensível a maiúsculas e minúsculas. Ao usar o encaminhamento sensível a maiúsculas e minúsculas, a sua API devolve um código de estado HTTP de 404 quando o método pedido no URL não corresponde ao nome do método da API indicado na sua especificação OpenAPI. Tenha em atenção que as frameworks de aplicações Web, como o Node.js Express, têm uma definição para ativar ou desativar o encaminhamento sensível a maiúsculas e minúsculas. O comportamento predefinido depende da framework que está a usar. Recomendamos que reveja as definições na sua estrutura para se certificar de que o encaminhamento sensível a maiúsculas e minúsculas está ativado. Esta recomendação está de acordo com a especificação OpenAPI v2.0, que afirma: "Todos os nomes dos campos na especificação são sensíveis a maiúsculas e minúsculas".

Exemplo

Parta do princípio de que:

A definição de x-google-allow é all.
O método da API widgets está listado na sua especificação OpenAPI, mas não Widgets.
Configurou a sua especificação OpenAPI para exigir uma chave da API.

Uma vez que widgets está listado na sua especificação OpenAPI, o ESP bloqueia o seguinte pedido porque não tem uma chave da API:

https://my-project-id.appspot.com/widgets

Uma vez que Widgets não está listado na sua especificação OpenAPI, o ESP passa o seguinte pedido para o seu serviço sem uma chave da API:

https://my-project-id.appspot.com/Widgets/

Se a sua API usar o encaminhamento sensível a maiúsculas e minúsculas (e não tiver encaminhado chamadas para "Widgets" para nenhum código), o back-end da API devolve um 404. No entanto, se estiver a usar o encaminhamento não sensível a maiúsculas e minúsculas, o back-end da API encaminha esta chamada para "widgets".

Os diferentes idiomas e frameworks têm métodos diferentes para controlar a sensibilidade a maiúsculas e minúsculas e o encaminhamento. Consulte a documentação da sua framework para ver detalhes.

`x-google-backend`

A extensão x-google-backend especifica como encaminhar pedidos para back-ends locais ou remotos. A extensão pode ser especificada ao nível superior e/ou ao nível da operação de uma especificação OpenAPI.

Por predefinição, o ESP está configurado para usar proxy de todo o tráfego para um único back-end local. O endereço do back-end local é especificado pela flag --backend (predefinição: http://127.0.0.1:8081). Pode usar a extensão x-google-backend para substituir este comportamento predefinido e especificar um ou mais back-ends locais ou remotos que podem receber pedidos.

A extensão x-google-backend também pode configurar outras definições para back-ends locais e remotos, como a autenticação e os limites de tempo. Todas estas configurações podem ser aplicadas por operação.

A extensão x-google-backend contém os seguintes campos:

`address`

address: URL

Opcional. O URL do back-end de destino. O esquema do endereço tem de ser http ou https.

Quando o encaminhamento é feito para back-ends remotos (sem servidor), o endereço deve ser definido e a parte do esquema deve ser https.

Se uma operação usar x-google-backend, mas não especificar address, o ESPv2 encaminha os pedidos para o back-end local especificado pela flag --backend.

`jwt_audience | disable_auth`

Apenas uma destas duas propriedades deve ser definida.

Se uma operação usar x-google-backend, mas não especificar jwt_audience nem disable_auth, o ESPv2 vai definir automaticamente o jwt_audience como predefinição para corresponder ao address. Se address não estiver definido, o ESPv2 define automaticamente disable_auth como true.

`jwt_audience`

jwt_audience: string

Opcional. O público-alvo do JWT especificado quando o ESPv2 obtém um token de ID de instância, que é usado quando faz o pedido de back-end de destino.

Quando configurar os pontos finais para o Serverless, o back-end remoto deve ser protegido para permitir apenas tráfego do ESPv2. O ESPv2 anexa um token de ID da instância ao cabeçalho Authorization quando encaminha pedidos por proxy. O token de ID da instância representa a conta de serviço de tempo de execução que foi usada para implementar o ESPv2. Em seguida, o back-end remoto pode validar se o pedido é proveniente do ESPv2 com base neste token anexado.

Por exemplo, um back-end remoto implementado no Cloud Run pode usar a IAM para:

Restrinja invocações não autenticadas revogando roles/run.invoker do principal especial allUsers.
Permita que apenas o ESPv2 invoque o back-end concedendo a função roles/run.invoker à conta de serviço de tempo de execução do ESPv2.

Por predefinição, o ESPv2 cria o token de ID da instância com um público-alvo JWT que corresponde ao campo address. A especificação manual jwt_audience só é necessária quando o back-end de destino usa a autenticação baseada em JWT e o público esperado é diferente do valor especificado no campo address. Para back-ends remotos implementados no App Engine ou com a IAP, tem de substituir o público-alvo do JWT. O App Engine e o IAP usam o respetivo ID de cliente OAuth como público-alvo esperado.

Quando esta funcionalidade está ativada, o ESPv2 altera os cabeçalhos nos pedidos. Se um pedido já tiver o cabeçalho Authorization definido, o ESPv2:

Copie o valor original para um novo cabeçalho X-Forwarded-Authorization.
Substitua o cabeçalho Authorization pelo token do ID da instância.

Por conseguinte, se um cliente da API definir o cabeçalho Authorization, um back-end em execução atrás do ESPv2 deve usar o cabeçalho X-Forwarded-Authorization para obter o JWT completo. O back-end tem de validar o JWT neste cabeçalho, uma vez que o ESPv2 não faz a validação quando os métodos de autenticação não estão configurados.

`disable_auth`

disable_auth: bool

Opcional. Esta propriedade determina se o ESPv2 deve impedir a obtenção de um token de ID da instância e impedir a respetiva anexação ao pedido.

Ao configurar o back-end de destino, pode não querer usar a IAP ou a IAM para autenticar pedidos do ESPv2 se se aplicar uma das seguintes condições:

O back-end deve permitir invocações não autenticadas.
O back-end requer o cabeçalho Authorization original do cliente da API e não pode usar X-Forwarded-Authorization (descrito na secção jwt_audience).

Neste caso, defina este campo como true.

`path_translation`

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Opcional. Define a estratégia de tradução de caminhos usada pelo ESPv2 quando encaminha pedidos para o back-end de destino.

Para mais detalhes sobre a tradução de caminhos, consulte a secção Compreender a tradução de caminhos.

Quando x-google-backend é usado no nível superior da especificação OpenAPI, path_translation é predefinido como APPEND_PATH_TO_ADDRESS e, quando x-google-backend é usado no nível de operação da especificação OpenAPI, path_translation é predefinido como CONSTANT_ADDRESS. Se o campo address estiver em falta, path_translation permanece não especificado e não ocorre.

`deadline`

deadline: double

Opcional. O número de segundos a aguardar por uma resposta completa de um pedido. As respostas que demorarem mais do que o prazo configurado vão expirar. O prazo predefinido é de 15.0 segundos.

Os valores não positivos não são aceites. O ESPv2 usa automaticamente o valor predefinido nestes casos.

Não é possível desativar o prazo, mas pode defini-lo para um número elevado, por exemplo, 3600.0 para uma hora.

`protocol`

protocol: [ http/1.1 | h2 ]

Opcional. O protocolo usado para enviar um pedido para o back-end. Os valores suportados são http/1.1 e h2.

O valor predefinido é http/1.1 para back-ends HTTP e HTTPS.

Para back-ends HTTP seguros (https://) que suportam HTTP/2, defina este campo como h2 para um desempenho melhorado. Esta é a opção recomendada para Google Cloud backends sem servidor.

Ativar a compatibilidade com back-ends no ESP

O ESPv2 deteta automaticamente quando o x-google-backend está configurado.

O ESP requer uma alteração de configuração manual para ativar esta funcionalidade. Ative o suporte do x-google-backend no ESP fornecendo o argumento --enable_backend_routing quando executar o contentor do ESP. (Para os tempos de execução em que não controla as opções do contentor do ESP, esta opção já está disponível.) Segue-se um exemplo de como ativar a compatibilidade com o x-google-backend quando implementar o contentor do ESP no GKE (este exemplo baseia-se no exemplo do tutorial sobre os Endpoints no GKE):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Compreender a tradução de caminhos

À medida que o ESP processa os pedidos, segue o caminho do pedido original e traduz o pedido antes de o enviar ao back-end de destino. A forma exata como esta tradução ocorre depende da estratégia de tradução de caminhos que está a usar. Existem duas estratégias de tradução de caminhos:

APPEND_PATH_TO_ADDRESS: o caminho do pedido de back-end de destino é calculado anexando o caminho do pedido original ao URL address da extensão x-google-backend.
CONSTANT_ADDRESS: O caminho do pedido de destino é constante, conforme definido pelo URL da extensão x-google-backend.address Se o caminho OpenAPI correspondente contiver parâmetros, o nome do parâmetro e o respetivo valor tornam-se parâmetros de consulta.

Exemplos:

APPEND_PATH_TO_ADDRESS
- address: https://my-project-id.appspot.com/BASE_PATH
- Com parâmetros de caminho da OpenAPI
  - Caminho da OpenAPI: /hello/{name}
  - Caminho do pedido: /hello/world
  - URL do pedido de destino: https://my-project-id.appspot.com/BASE_PATH/hello/world
- Sem parâmetros de caminho da OpenAPI
  - Caminho da OpenAPI: /hello
  - Caminho do pedido: /hello
  - URL do pedido de destino: https://my-project-id.appspot.com/BASE_PATH/hello
CONSTANT_ADDRESS
- address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
- Com parâmetros de caminho da OpenAPI
  - Caminho da OpenAPI: /hello/{name}
  - Caminho do pedido: /hello/world
  - URL do pedido de destino: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
- Sem parâmetros de caminho da OpenAPI
  - Caminho da OpenAPI: /hello
  - Caminho do pedido: /hello
  - URL do pedido de destino: https://us-central1-my-project-id.cloudfunctions.net/helloGET

`x-google-endpoints`

Esta secção descreve as utilizações da extensão x-google-endpoints.

Configurar o DNS no domínio `cloud.goog`

Se implementou a sua aplicação no Compute Engine ou no Google Kubernetes Engine, pode criar uma entrada DNS para o seu serviço Endpoints no domínio cloud.goog adicionando o seguinte ao seu documento OpenAPI:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Adicione a extensão x-google-endpoints ao nível superior do seu documento OpenAPI (sem recuos nem aninhamentos). Tem de configurar o nome de domínio no formato: .endpoints.PROJECT_ID.cloud.goog

Por exemplo:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  target: "192.0.2.1"

O domínio .cloud.goog é gerido pela Google e partilhado por Google Cloud clientes. Uma vez que os Google Cloud IDs dos projetos são globalmente exclusivos, um nome de domínio no formato .endpoints.PROJECT_ID.cloud.goog é um nome de domínio exclusivo para a sua API.

Para simplificar, configure o campo host e o campo x-google-endpoints.name para serem iguais. Quando implementa o seu documento OpenAPI, o Service Management cria:

Um serviço gerido com o nome que especificou no campo host.
Um registo A de DNS que usa o nome e o endereço IP que configurou na extensão x-google-endpoints.

Para APIs alojadas no ambiente flexível do App Engine, pode usar o domínio appspot.com. Para mais informações, consulte o artigo Configurar pontos finais.

Configurar o ESP para permitir pedidos CORS

Se a sua API for chamada a partir de uma aplicação Web numa origem diferente, a sua API tem de suportar a partilha de recursos de origem cruzada (CORS). Consulte o artigo Adicionar suporte de CORS ao ESP para obter informações sobre a configuração do ESP para suportar CORS.

Se precisar de implementar compatibilidade com CORS personalizada no código do back-end, defina allowCors: True para que o ESP transmita todos os pedidos CORS para o código do back-end:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Adicione a extensão x-google-endpoints ao nível superior do seu documento OpenAPI (sem recuo nem aninhamento), por exemplo:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

`x-google-issuer`

x-google-issuer: URI | EMAIL_ADDRESS

Esta extensão é usada na secção securityDefinitions do OpenAPI para especificar o emissor de uma credencial. Os valores podem assumir a forma de um nome de anfitrião ou de um endereço de email.

`x-google-jwks_uri`

x-google-jwks_uri: URI

URI do conjunto de chaves públicas do fornecedor para validar a assinatura do token Web JSON.

O ESP suporta dois formatos de chave pública assimétricos definidos pela extensão x-google-jwks_uri OpenAPI:

Formato de conjunto JWK. Por exemplo:

x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

X509. Por exemplo:

x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Se estiver a usar um formato de chave simétrica, defina x-google-jwks_uri para o URI de um ficheiro que contenha a string da chave codificada em base64url.

Se omitir x-google-jwks_uri, o ESP segue o protocolo OpenID Connect Discovery para descobrir automaticamente o URI JWKS para o fornecedor OpenID especificado. O ESP faz um pedido a x-google-issuer/.well-known/openid-configuration, analisa a resposta JSON e lê o URI JWKS do campo jwks_uri de nível superior.

Tenha em atenção que a omissão de x-google-jwks_uri resulta em tempos de início a frio mais elevados, uma vez que o ESP tem de fazer uma chamada remota adicional no início. Por conseguinte, só é recomendável omitir este campo se o URI JWKS mudar com frequência. A maioria dos fornecedores OpenID certificados (como a Google, a Auth0 e a Okta) tem URIs JWKS estáveis.

`x-google-jwt-locations`

Por predefinição, um JWT é transmitido no cabeçalho Authorization (com o prefixo "Bearer "), no cabeçalho X-Goog-Iap-Jwt-Assertion ou no parâmetro de consulta access_token. Consulte o artigo Fazer uma chamada autenticada a uma API Endpoints para ver exemplos de transmissão de um JWT.

Em alternativa, use a extensão x-google-jwt-locations na secção securityDefinitions do OpenAPI para fornecer as localizações personalizadas a partir das quais extrair o token JWT.

A extensão x-google-jwt-locations aceita uma lista de localizações de JWT. Cada localização do JWT contém os seguintes campos:

Elemento	Descrição
`header/query`	Obrigatório. O nome do cabeçalho que contém o JWT ou o nome do parâmetro de consulta que contém o JWT.
`value_prefix`	Opcional. Apenas para o cabeçalho. Quando o elemento `value_prefix` está definido, o respetivo valor tem de corresponder ao prefixo do valor do cabeçalho que contém o JWT.

Por exemplo:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Se quiser suportar apenas um subconjunto das localizações JWT predefinidas, liste-as explicitamente na extensão x-google-jwt-locations. Por exemplo, para incluir suporte apenas para o cabeçalho Authorization com o prefixo "Bearer ":

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

`x-google-audiences`

x-google-audiences: STRING

Esta extensão é usada na secção securityDefinitions do OpenAPI para fornecer uma lista de públicos-alvo com os quais o campo aud do JWT deve corresponder durante a autenticação JWT. Esta extensão aceita uma única string com valores separados por uma vírgula. Não são permitidos espaços entre os públicos-alvo. Quando não é especificado, o campo aud do JWT deve corresponder ao campo host no documento OpenAPI, a menos que seja usada a flag --disable_jwt_audience_service_name_check. Se a flag for usada e x-google-audiences não for especificado, o campo aud do JWT não é verificado.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

`x-google-management`

A extensão x-google-management controla diferentes aspetos da gestão de APIs e contém os campos descritos nesta secção.

`metrics`

Use metrics juntamente com quota e x-google-quota para configurar uma quota para a sua API. Uma quota permite-lhe controlar a taxa à qual as aplicações podem chamar os métodos na sua API. Por exemplo:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

O campo metrics contém uma lista com os seguintes pares de chave-valor:

Elemento	Descrição
nome	Obrigatório. O nome desta métrica. Normalmente, este é o tipo de pedido (por exemplo, "read-requests" ou "write-requests") que identifica exclusivamente a métrica.
displayName	Opcional, mas recomendado. O texto apresentado para identificar a métrica no separador Quotas na página Endpoints > Serviços naGoogle Cloud consola. Este texto também é apresentado aos consumidores da sua API nas páginas Quotas em IAM e administração e APIs e serviços. O nome a apresentar tem de ter um máximo de 40 carateres. Para fins de legibilidade, a unidade do limite de quota associado é anexada automaticamente ao nome a apresentar naGoogle Cloud consola. Por exemplo, se especificar "Pedidos de leitura" para o nome a apresentar, é apresentado "Pedidos de leitura por minuto por projeto" naGoogle Cloud consola. Se não for especificado, a "quota não etiquetada" é apresentada aos consumidores da sua API nas páginas Quotas em IAM e administrador e APIs e serviços. Para manter a consistência com os nomes a apresentar dos serviços Google indicados na página Quotas que os consumidores da sua API veem, recomendamos o seguinte para o nome a apresentar: Use "Pedidos" quando tiver apenas uma métrica. Quando tem várias métricas, cada uma deve descrever o tipo de pedido e conter a palavra "pedidos" (por exemplo, "Pedidos de leitura" ou "Pedidos de escrita"). Use "unidades de quota" em vez de "pedidos" quando qualquer um dos custos associados à métrica for superior a 1.
valueType	Obrigatório. Tem de ser INT64
metricKind	Obrigatório. Tem de ser DELTA

`quota`

Especifica o limite de quota para uma métrica definida na secção quota. Por exemplo:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

O campo quota.limits contém uma lista com os seguintes pares de chave:valor:

Elemento	Descrição
nome	Obrigatório. Nome do limite, que tem de ser exclusivo no serviço. O nome pode conter letras maiúsculas e minúsculas, números e "-" (o caráter de traço) e tem de ter um comprimento máximo de 64 carateres.
métrica	Obrigatório. O nome da métrica à qual este limite se aplica. Este nome tem de corresponder ao texto especificado no nome de uma métrica. Se o texto especificado não corresponder a um nome de métrica, recebe um erro quando implementa o documento OpenAPI.
unidade	Obrigatório. A unidade do limite. Atualmente, apenas "1/min/{project}" é suportado, o que significa que o limite é aplicado por projeto e a utilização é reposta a cada minuto.
valores	Obrigatório. O limite da métrica. Tem de especificar isto como um par chave:valor no seguinte formato: STANDARD: `YOUR-LIMIT-FOR-THE-METRIC` Substitui `YOUR-LIMIT-FOR-THE-METRIC` por um valor inteiro que é o número máximo de pedidos permitidos para a unidade especificada (que atualmente é apenas por minuto e por projeto). Por exemplo: values: STANDARD: 5000

`x-google-quota`

A extensão x-google-quota é usada na secção paths do OpenAPI para associar um método na sua API a uma métrica. Os métodos que não têm o elemento x-google-quota definido não têm limites de quota aplicados. Por exemplo:

x-google-quota:
  metricCosts:
    read-requests: 1

A extensão x-google-quota contém o seguinte item:

Elemento Descrição

metricCosts

Elemento	Descrição
metricCosts	Um par de chave:valor definido pelo utilizador: `"YOUR-METRIC-NAME": METRIC-COST`. `"YOUR-METRIC-NAME":` O texto para `"YOUR-METRIC-NAME"` tem de corresponder a um nome de métrica definido. `METRIC-COST:` Um valor inteiro que define o custo para cada pedido. Quando é feito um pedido, a métrica associada é incrementada pelo custo especificado. O custo permite que os métodos consumam a métrica ao mesmo ritmo. Por exemplo, se uma métrica tiver um limite de quota de 1000 e um custo de 1, a aplicação de chamada pode fazer 1000 pedidos por minuto antes de exceder o limite. Com um custo de 2 para a mesma métrica, uma aplicação de chamadas só pode fazer 500 pedidos por minuto antes de exceder o limite.

Um par de chave:valor definido pelo utilizador: "YOUR-METRIC-NAME": METRIC-COST.

"YOUR-METRIC-NAME": O texto para "YOUR-METRIC-NAME" tem de corresponder a um nome de métrica definido.
METRIC-COST: Um valor inteiro que define o custo para cada pedido. Quando é feito um pedido, a métrica associada é incrementada pelo custo especificado. O custo permite que os métodos consumam a métrica ao mesmo ritmo. Por exemplo, se uma métrica tiver um limite de quota de 1000 e um custo de 1, a aplicação de chamada pode fazer 1000 pedidos por minuto antes de exceder o limite. Com um custo de 2 para a mesma métrica, uma aplicação de chamadas só pode fazer 500 pedidos por minuto antes de exceder o limite.

Exemplos de quotas

O exemplo seguinte mostra a adição de uma métrica e um limite para pedidos de leitura e pedidos de gravação.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

`x-google-api-name`

Quando o seu serviço contém apenas uma API, o nome da API é igual ao nome do serviço do Endpoints. (O Endpoints usa o nome que especificar no campo host do seu documento OpenAPI como o nome do seu serviço.) Quando o seu serviço contém mais do que uma API, especifica os nomes das APIs adicionando a extensão x-google-api-name ao seu documento OpenAPI. A extensão x-google-api-name permite-lhe nomear explicitamente APIs individuais e estabelecer uma gestão de versões independente para cada API.

Por exemplo, pode configurar um serviço denominado api.example.com com duas APIs, producer e consumer, com os fragmentos do documento OpenAPI abaixo:

API Producer em producer.yaml:

swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

API Consumer em consumer.yaml:

swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

Pode implementar os dois documentos OpenAPI em conjunto com:

gcloud endpoints services deploy producer.yaml consumer.yaml

Extensões OpenAPI Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Convenção de nomenclatura

x-google-allow

Exemplo

x-google-backend

address

jwt_audience | disable_auth

jwt_audience

disable_auth

path_translation

deadline

protocol

Ativar a compatibilidade com back-ends no ESP

Compreender a tradução de caminhos

x-google-endpoints

Configurar o DNS no domínio cloud.goog