Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Limitazioni delle funzionalità di OpenAPI 2.0

OpenAPI | gRPC

Le seguenti sezioni descrivono le limitazioni delle funzionalità di OpenAPI 2.0 in Endpoints.

Ambiti ignorati

Sebbene Endpoints accetti documenti OpenAPI con ambiti definiti in un oggetto schema di sicurezza, quando una richiesta viene inviata alla tua API, né Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2) né Cloud Endpoints Frameworks controllano gli ambiti definiti.

Più requisiti di sicurezza

Puoi specificare più di un requisito di sicurezza nel documento OpenAPI. Questa sezione descrive gli schemi di sicurezza supportati da ESP e ESPv2.

Requisiti di sicurezza contenenti una chiave API

ESP e ESPv2 non supportano requisiti di sicurezza alternativi (OR logico) quando uno degli schemi di sicurezza è una chiave API. Ad esempio, ESP e ESPv2 non supportano il seguente elenco di requisiti di sicurezza:

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

Questa definizione richiede che un'operazione accetti le richieste che seguono i requisiti petstore_auth o i requisiti api_key.

Tieni presente, tuttavia, che ESP e ESPv2 supportano le congiunzioni dei requisiti di sicurezza (AND logico), quindi puoi richiedere sia una chiave API sia l'autenticazione OAuth2. Ad esempio, il seguente elenco di requisiti di sicurezza è supportato:

security:
- petstore_auth: []
  api_key: []

Questa definizione richiede che un'operazione accetti le richieste che seguono contemporaneamente i requisiti petstore_auth e i requisiti api_key.

Requisiti di sicurezza per OAuth2

ESP e ESPv2 supportano requisiti di sicurezza alternativi (OR logico), ma solo per gli schemi di sicurezza di autenticazione OAuth2. Ad esempio, il seguente elenco di requisiti di sicurezza è supportato:

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

Convalida della definizione di sicurezza

ESP e ESPv2 non convalidano che tutti i requisiti di sicurezza (a livello API o di metodo) siano presenti anche nella sezione securityDefinitions. Di conseguenza, se la specifica API utilizza uno schema di sicurezza non definito, le richieste non autenticate potrebbero passare attraverso l'API, a livello in cui è configurato il token di sicurezza non definito. Assicurati che tutte le chiavi di sicurezza utilizzate dalla tua API e dai relativi metodi siano definite nelle definizioni di sicurezza del documento OpenAPI.

Modelli di percorso dell'URL

Endpoints supporta solo i parametri dei modelli di percorso dell'URL che corrispondono a segmenti di percorso interi (delimitati da barre /). I parametri dei modelli di percorso dell'URL che corrispondono a segmenti di percorso parziali non sono supportati.

Ad esempio, i seguenti modelli di percorso dell'URL sono supportati:

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

I seguenti modelli di percorso dell'URL non sono supportati e verranno rifiutati:

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

Operazioni sul percorso radice dell'URL `/`

Endpoints accetta documenti OpenAPI che includono operazioni sul percorso radice /. Tuttavia, le richieste sul percorso radice vengono rifiutate da ESP. Tieni presente che questa limitazione riguarda solo ESP, ESPv2 supporta il percorso radice /.

Ad esempio, il seguente snippet di documento OpenAPI è accettato:

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

Tuttavia, le richieste successive per POST / vengono rifiutate con il seguente errore:

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

Caricamento file

Endpoints non accetta type: file per i parametri di caricamento dei file, ma deve essere utilizzato type: string.

Ad esempio, il seguente snippet type: file non è consentito:

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

Mentre il seguente con type: string è consentito:

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

Parametri, schemi e tipi

ESP e ESPv2 ignorano la maggior parte delle definizioni di parametri e tipi.

Endpoints accetta documenti OpenAPI che includono definizioni di parametri e tipi obbligatori, ma ESP e ESPv2 non applicano queste definizioni e inoltrano le richieste in entrata alla tua API. Di seguito è riportato un elenco parziale che fornisce esempi delle definizioni che ESP e ESPv2 non applicano:

Parametri dei dati dei moduli, ad esempio:

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

Parametri obbligatori, ad esempio:

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

Formati di raccolta di array, ad esempio:

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

Composizione del tipo, ad esempio:

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

Oggetti di risposta diversi per codice di stato, ad esempio:

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

Riferimenti a tipi esterni

Endpoints non supporta i riferimenti a tipi esterni a un documento OpenAPI. Ad esempio, Endpoints rifiuta i documenti OpenAPI che includono:

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

Porta personalizzata nell'indirizzo dell'host del servizio

Endpoints non consente porte personalizzate nel campo host di un documento OpenAPI. Ad esempio, Endpoints rifiuta documenti OpenAPI come:

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

Limitazioni degli alias YAML

Endpoints può supportare fino a 200 nodi alias YAML in un documento OpenAPI. Se in un documento OpenAPI sono presenti più di 200 alias YAML, ti consigliamo di dereferenziare gli alias, ove possibile, per rispettare questo limite.

Bug noti

Di seguito è riportato un elenco di problemi noti.

Documenti OpenAPI rifiutati

Quando esegui il deployment del documento OpenAPI utilizzando gcloud endpoints services deploy, Endpoints rifiuta i documenti OpenAPI che includono:

Parametri del corpo di array, ad esempio:

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

Percorsi con barre finali, ad esempio:

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

Per risolvere il problema, rimuovi la barra finale da /echo/:

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

Limitazioni della definizione della chiave API

Quando specifichi una chiave API nell'oggetto delle definizioni di sicurezza nel documento OpenAPI, Endpoints richiede uno dei seguenti schemi:

name è key e in è query
name è api_key e in è query
name è x-api-key e in è header

Ad esempio:

"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 esegui il deployment di un documento OpenAPI con altri tipi di definizioni di sicurezza della chiave API, Endpoints potrebbe accettarli e generare un avviso. Tuttavia, le definizioni di sicurezza della chiave API vengono ignorate nelle richieste in entrata.

Limitazioni delle funzionalità di OpenAPI 2.0 Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.