Einschränkungen der OpenAPI 2.0-Funktionen

In den folgenden Abschnitten werden die Einschränkungen der OpenAPI 2.0-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 der Extensible Service Proxy V2 (ESPv2) noch Cloud Endpoints Frameworks die definierten Bereiche.

Mehrere Sicherheitsanforderungen

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

Sicherheitsanforderungen, die einen API-Schlüssel enthalten

Der ESP und ESPv2 unterstützen keine alternativen Sicherheitsanforderungen (logisches ODER), wenn eines der Sicherheitsschemas ein API-Schlüssel ist. Der ESP und ESPv2 unterstützen beispielsweise nicht 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 und ESPv2 miteinander verknüpfte Sicherheitsanforderungen (logisches UND) unterstützen, 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 und ESPv2 unterstützen 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 und ESPv2 validieren nicht, dass 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 auf der Ebene, auf der der nicht definierte Sicherheitsschlüssel konfiguriert ist, über die API eingehen. Achten Sie darauf, dass alle von Ihrer API und ihren Methoden verwendeten Sicherheitsschlüssel in Ihrem OpenAPI-Dokument unter den Sicherheitsdefinitionen 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

Cloud Endpoints akzeptiert type: file nicht für Parameter zum Hochladen von Dateien. Verwenden Sie stattdessen type: string.

Das folgende type: file-Snippet ist beispielsweise 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.

Das folgende type: string-Snippet ist jedoch 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

Der ESP und ESPv2 ignorieren die meisten Parameter- und Typdefinitionen.

Cloud Endpoints akzeptiert OpenAPI-Dokumente, die erforderliche Parameter- und Typdefinitionen enthalten. Der ESP und ESPv2 erzwingen diese Definition jedoch nicht und leiten eingehende Anfragen an Ihre API weiter. Im Folgenden finden Sie eine unvollständige Liste mit Beispielen für Definitionen, die der ESP und ESPv2 akzeptieren, aber nicht erzwingen:

• Formulardatenparameter:

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

• Erforderliche Parameter:

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

• Arraysammlungsformate: