Einschränkungen der OpenAPI-Funktionen

Derzeit akzeptiert Cloud Endpoints nur Version 2 der OpenAPI-Spezifikation.

In den folgenden Abschnitten werden die Einschränkungen der OpenAPI-Funktionen auf Cloud Endpoints beschrieben.

Ignorierte Bereiche

Obwohl Cloud Endpoints OpenAPI-Dokumente akzeptiert, für die in einem Sicherheitsschemaobjekt Bereiche definiert wurden, überprüfen beim Senden einer Anfrage an Ihre API weder der Extensible Service Proxy (ESP) noch Cloud Endpoints Frameworks die definierten Bereiche.

Mehrere Sicherheitsanforderungen

Sie können in Ihrem OpenAPI-Dokument mehrere Sicherheitsanforderungen angeben. In diesem Abschnitt werden die vom ESP unterstützten Sicherheitsschemas beschrieben.

Sicherheitsanforderungen, die einen API-Schlüssel enthalten

Der ESP unterstützt keine alternativen Sicherheitsanforderungen (logisches ODER), wenn eines der Sicherheitsschemas ein API-Schlüssel ist. Beispielsweise bietet der ESP keine Unterstützung für die folgende Liste von Sicherheitsanforderungen:

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

Diese Definition erfordert, dass ein Vorgang Anfragen akzeptiert, die den petstore_auth- oder den api_key-Anforderungen entsprechen.

Beachten Sie jedoch, dass der ESP miteinander verknüpfte Sicherheitsanforderungen (logisches UND) unterstützt, sodass Sie sowohl einen API-Schlüssel als auch die OAuth2-Authentifizierung festlegen können. Die folgende Liste von Sicherheitsanforderungen wird beispielsweise unterstützt:

security:
- petstore_auth: []
  api_key: []

Diese Definition erfordert einen Vorgang, um Anfragen zu akzeptieren, die gleichzeitig den Anforderungen von petstore_auth und api_key entsprechen.

Sicherheitsanforderungen für OAuth2

Der ESP unterstützt alternative Sicherheitsanforderungen (logisches ODER), jedoch nur für Sicherheitsschemas der OAuth2-Authentifizierung. Die folgende Liste von Sicherheitsanforderungen wird beispielsweise unterstützt:

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

Validierung der Sicherheitsdefinition

Der ESP überprüft nicht, ob alle Sicherheitsanforderungen (entweder auf API- oder Methodenebene) auch im Abschnitt securityDefinitions vorhanden sind. Wenn in der API-Spezifikation ein nicht definiertes Sicherheitsschema verwendet wird, können daher nicht authentifizierte Anfragen über die API auf der Ebene eingehen, auf der der nicht definierte Sicherheitsschlüssel konfiguriert ist. Achten Sie darauf, dass alle von der API verwendeten Sicherheitsschlüssel und deren Methoden in den Sicherheitsdefinitionen im OpenAPI-Dokument definiert sind.

URL-Pfadvorlagen

Endpoints unterstützt nur URL-Pfadvorlagenparameter, die vollständigen Pfadsegmenten entsprechen (durch Schrägstriche / getrennt). URL-Pfadvorlagenparameter, die Teilpfadsegmenten entsprechen, werden nicht unterstützt.

Die folgenden URL-Pfadvorlagen werden beispielsweise unterstützt:

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

Die folgenden URL-Pfadvorlagen werden nicht unterstützt und abgelehnt:

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

Vorgänge für den URL-Root-Pfad /

Cloud Endpoints akzeptiert OpenAPI-Dokumente, die Vorgänge im Root-Pfad // beinhalten. Anfragen für den Root-Pfad werden jedoch vom ESP abgelehnt. Hinweis: Diese Einschränkung gilt nur für ESP. ESPv2 unterstützt den Stammpfad /.

Das folgende OpenAPI-Dokument-Snippet wird beispielsweise akzeptiert:

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

Nachfolgende Anfragen für POST / werden jedoch mit dem folgenden Fehler abgelehnt:

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

Dateien hochladen

Endpoints akzeptiert type: file nicht für Dateiuploadparameter. Stattdessen sollte type: string verwendet werden.

Beispielsweise ist das folgende type: file-Snippet nicht zulässig:

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

Folgendes ist mit type: string zulässig:

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

Parameter, Schemas und Typen

ESP ignoriert die meisten Parameter- und Typdefinitionen.

Cloud Endpoints akzeptiert OpenAPI-Dokumente, die erforderliche Parameter- und Typdefinitionen enthalten. Der ESP erzwingt diese Definitionen jedoch nicht und leitet eingehende Anfragen an Ihre API weiter. Im Folgenden finden Sie eine unvollständige Liste mit Beispielen für Definitionen, die vom ESP nicht erzwungen werden:

  • Formulardatenparameter wie: 
    parameters:
- name: avatar
  in: formData
  description: "The avatar of the user"
  type: string
  • Erforderliche Parameter wie: 
    parameters:
- name: message
  in: query
  description: "Message to send"
  required: true
  type: string
  • Arraysammlungsformate wie: 
    parameters:
- name: items
  in: query
  description: "List of item IDs"
  required: true
  type: array
  items:
    type: string
  collectionFormat: tsv
  • Typerstellung wie: 
    definitions:
  base:
    properties:
      message:
        type: string
  extended:
    description: "Extends the base type"
    allOf:
    - $ref: "#/definitions/base"
    - type: object
      properties:
        extension:
          type: string
  • Verschiedene Antwortobjekte nach Statuscode wie: 
    responses:
  200:
    description: "Echo"
    schema:
      $ref: "#/definitions/EchoResponse"
  400:
    description: "Error"
    schema:
      type: string

Verweise auf externe Typen

Cloud Endpoints unterstützt keine Verweise auf Typen außerhalb eines OpenAPI-Dokuments. Cloud Endpoints lehnt beispielsweise OpenAPI-Dokumente ab, die Folgendes enthalten:

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

Benutzerdefinierter Port in Diensthostadresse

Endpoints lässt keine benutzerdefinierten Ports im Feld host eines OpenAPI-Dokuments zu. Cloud Endpoints lehnt beispielsweise folgende OpenAPI-Dokumente ab:

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

Einschränkungen für YAML-Aliasse

Endpunkte können bis zu 200 YAML-Alias-Knoten in einem OpenAPI-Dokument unterstützen. Wenn ein OpenAPI-Dokument mehr als 200 YAML-Aliasse enthält, empfehlen wir, Aliasse nach Möglichkeit zu dereferenzieren, um dieses Limit einzuhalten.

Bekannte Programmfehler

OpenAPI-Dokumente abgelehnt

Wenn Sie ein OpenAPI-Dokument mit gcloud endpoints services deploy bereitstellen, lehnt Endpoints OpenAPI-Dokumente ab, die Folgendes enthalten:

  • Arraytextparameter wie: 
    parameters:
- name: message
  description: "Message to echo"
  in: body
  schema:
    type: array
    items:
      type: string
  • Pfade mit abschließenden Schrägstrichen, zum Beispiel: 
    paths:
  "/echo/":
    post:
      description: "Echo back a given message."

    Entfernen Sie den abschließenden Schrägstrich aus /echo/, um dieses Problem zu beheben:

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

Einschränkungen bei der API-Schlüsseldefinition

Bei der Angabe eines API-Schlüssels im Objekt für Sicherheitsdefinitionen in Ihrem OpenAPI-Dokument erfordert Endpoints eines der folgenden Schemas:

  • Der name ist key und der in ist query
  • Der name ist api_key und der in ist query
  • Der name ist x-api-key und der in ist header

Beispiel:

"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"
    },
}

Wenn Sie ein OpenAPI-Dokument mit anderen Arten von Sicherheitsdefinitionen für API-Schlüssel bereitstellen, akzeptiert Cloud Endpoints diese möglicherweise und gibt eine Warnung aus. Die API-Schlüssel-Sicherheitsdefinitionen werden jedoch in eingehenden Anfragen ignoriert.

Das Cloud Endpoints-Portal kann keine Zusammensetzungstypen darstellen

Obwohl Endpoints OpenAPI-Dokumente mit Kompositionstypen akzeptiert, d. h. Typen mit allOf in der Definition, generiert das Endpoints-Portal keine Dokumentation für Kompositionstypen.