Esta página foi traduzida pela API Cloud Translation.

Limitações das funcionalidades da OpenAPI

OpenAPI | gRPC

O Cloud Endpoints só aceita a versão 2 da especificação OpenAPI.

As secções seguintes descrevem as limitações das funcionalidades da OpenAPI nos pontos finais.

Âmbitos ignorados

Embora os Endpoints aceitem documentos OpenAPI com âmbitos definidos num objeto de esquema de segurança, quando é enviado um pedido para a sua API, nem o Extensible Service Proxy (ESP), o Extensible Service Proxy V2 (ESPv2) nem os Cloud Endpoints Frameworks verificam os âmbitos definidos.

Vários requisitos de segurança

Pode especificar mais do que um requisito de segurança no seu documento OpenAPI. Esta secção descreve os esquemas de segurança suportados pelo ESP e ESPv2.

Requisitos de segurança que contêm uma chave da API

O ESP e o ESPv2 não suportam requisitos de segurança alternativos (OR lógico) quando um dos esquemas de segurança é uma chave de API. Por exemplo, o ESP e o ESPv2 não suportam a seguinte lista de requisitos de segurança:

security:
- petstore_auth: []
- api_key: []

Esta definição requer que uma operação aceite pedidos que cumpram os petstore_authrequisitosou os api_keyrequisitos.

No entanto, tenha em atenção que o ESP e o ESPv2 suportam conjunções de requisitos de segurança (AND lógico), pelo que pode exigir uma chave da API e a autenticação OAuth2. Por exemplo, a seguinte lista de requisitos de segurança é suportada:

security:
- petstore_auth: []
  api_key: []

Esta definição requer uma operação para aceitar pedidos que, em simultâneo, cumpram os petstore_authrequisitose os api_keyrequisitos.

Requisitos de segurança para o OAuth2

O ESP e o ESPv2 suportam requisitos de segurança alternativos (OR lógico), mas apenas para esquemas de segurança de autenticação OAuth2. Por exemplo, a seguinte lista de requisitos de segurança é suportada:

security:
  - firebase1: []
  - firebase2: []

Validação da definição de segurança

O ESP e o ESPv2 não validam se todos os requisitos de segurança (ao nível da API ou do método) também estão presentes na secção securityDefinitions. Como resultado, se a especificação da API usar um esquema de segurança indefinido, os pedidos não autenticados podem ser processados através da API, ao nível em que a chave de segurança indefinida está configurada. Certifique-se de que todas as chaves de segurança usadas pela sua API e respetivos métodos estão definidos nas definições de segurança no seu documento OpenAPI.

Criação de modelos de caminhos de URLs

Os pontos finais só suportam parâmetros de modelo de caminho de URL que correspondam a segmentos de caminho completos (delimitados por barras /). Os parâmetros de modelo de caminho de URL que correspondam a segmentos de caminho parciais não são suportados.

Por exemplo, são suportados os seguintes modelos de caminho de URL:

/items/{itemId}
/items/{itemId}/subitems

Os seguintes modelos de caminho de URL não são suportados e vão ser rejeitados:

/items/overview.{format}
/items/prefix_{id}_suffix

Operações no caminho raiz do URL `/`

Os pontos finais aceitam documentos OpenAPI que incluem operações no caminho raiz /. No entanto, os pedidos no caminho raiz são rejeitados pelo ESP. Tenha em atenção que esta limitação é apenas para o ESP. O ESPv2 suporta o caminho raiz /.

Por exemplo, o seguinte fragmento de documento OpenAPI é aceite:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

No entanto, os pedidos subsequentes de POST / são rejeitados com o seguinte erro:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

Carregamento de ficheiro

Os pontos finais não aceitam o parâmetro type: file para parâmetros de carregamento de ficheiros. Em alternativa, deve usar o parâmetro type: string.

Por exemplo, o seguinte fragmento type: file não é permitido:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

Por outro lado, a Google permite o seguinte com type: string:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

Parâmetros, esquemas e tipos

O ESP e o ESPv2 ignoram a maioria das definições de parâmetros e tipos.

O Endpoints aceita documentos OpenAPI que incluem definições de parâmetros e tipos obrigatórios, mas o ESP e o ESPv2 não aplicam estas definições e encaminham os pedidos recebidos para a sua API. Segue-se uma lista parcial que fornece exemplos das definições que o ESP e o ESPv2 não aplicam:

Parâmetros de dados de formulários, como:

parameters:
- name: avatar
  in: formData
  description: "The avatar of the user"
  type: string

Parâmetros obrigatórios, como:

parameters:
- name: message
  in: query
  description: "Message to send"
  required: true
  type: string

Formatos de recolha de matrizes, como:

parameters:
- name: items
  in: query
  description: "List of item IDs"
  required: true
  type: array
  items:
    type: string
  collectionFormat: tsv

Tipo de composição, como:

definitions:
  base:
    properties:
      message:
        type: string
  extended:
    description: "Extends the base type"
    allOf:
    - $ref: "#/definitions/base"
    - type: object
      properties:
        extension:
          type: string

Diferentes objetos de resposta por código de estado, como:

responses:
  200:
    description: "Echo"
    schema:
      $ref: "#/definitions/EchoResponse"
  400:
    description: "Error"
    schema:
      type: string

Referências de tipo externo

Os pontos finais não suportam referências a tipos fora de um documento OpenAPI. Por exemplo, os Endpoints rejeitam documentos OpenAPI que incluem:

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

Endereço do anfitrião do serviço de portabilidade personalizado

Os pontos finais não permitem portas personalizadas no campo host de um documento OpenAPI. Por exemplo, os Endpoints rejeitam documentos OpenAPI, como:

swagger: 2.0
host: example.com:8080
schemes:
- http

Limitações de alias do YAML

Os pontos finais podem suportar até 200 nós de alias YAML num documento OpenAPI. Se existirem mais de 200 aliases YAML num documento OpenAPI, recomendamos que anule a referência dos aliases sempre que possível para agir em conformidade com este limite.

Erros conhecidos

Documentos OpenAPI rejeitados

Quando implementa o seu documento OpenAPI através do gcloud endpoints services deploy, o Google Cloud Endpoints rejeita documentos OpenAPI que incluem:

Parâmetros do corpo da matriz, como:

parameters:
- name: message
  description: "Message to echo"
  in: body
  schema:
    type: array
    items:
      type: string

Caminhos com barras no final, por exemplo:

paths:
  "/echo/":
    post:
      description: "Echo back a given message."

Para corrigir este problema, remova a barra invertida final de /echo/:

paths:
  "/echo":
    post:
      description: "Echo back a given message."

Limitações da definição da chave da API

Quando especifica uma chave da API no objeto de definições de segurança no seu documento OpenAPI, o Endpoints requer um dos seguintes esquemas:

O name é key e o in é query
O name é api_key e o in é query
O name é x-api-key e o in é header

Por exemplo:

"securityDefinitions": {
  "api_key_0": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
    },
  "api_key_1": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
    }
  "api_key_2": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
    },
}

Quando implementa um documento OpenAPI com outros tipos de definições de segurança de chaves da API, os Endpoints podem aceitá-los e apresentar um aviso. No entanto, as definições de segurança da chave da API são ignoradas nos pedidos recebidos.

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