API als Typanbieter hinzufügen

Auf dieser Seite wird gezeigt, wie Sie Deployment Manager eine API als Typanbieter hinzufügen. Weitere Informationen zu Typen und Typanbietern finden Sie unter Typen.

Ein Typanbieter macht alle Ressourcen einer Drittanbieter-API in Deployment Manager als Basistypen verfügbar, die Sie in Ihren Konfigurationen verwenden können. Diese Typen müssen direkt von einer RESTful API bereitgestellt werden, die das Erstellen, Lesen, Aktualisieren und Löschen (CRUD) unterstützt.

Sie können eine beliebige API als Typanbieter verwenden, wenn die API eine OpenAPI-Spezifikation (früher als Swagger© bezeichnet) oder ein Google Discovery-Dokument hat. Fügen Sie Typanbieter hinzu, um APIs zu verwenden, die nicht automatisch von Google bereitgestellt werden.

In diesem Dokument wird nicht beschrieben, wie Sie sich Ihren eigenen API-Dienst einrichten. Es wird davon ausgegangen, dass es bereits eine API gibt, die Sie hinzufügen möchten, oder dass Sie bereits eine laufende API erstellt haben, die an einem öffentlichen Endpunkt zugänglich ist. Beispiel: Sie könnten eine Beispiel-API mit Google Cloud Endpoints bereitstellen. Dies wird in der Cloud Endpoints-Schnellstartanleitung beschrieben.

Hinweise

  • Wenn Sie die Befehlszeilenbeispiele in dieser Anleitung verwenden möchten, installieren Sie das gcloud-Befehlszeilentool.
  • Wenn Sie die API-Beispiele in dieser Anleitung verwenden möchten, richten Sie den API-Zugriff ein.
  • Richten Sie den V2Beta-API-Zugriff ein, wenn Sie die API-Beispiele in diesem Handbuch verwenden möchten.

Komponenten eines Typanbieters

Ein Typanbieter besteht aus:

  • Name: Der gewünschte Name des Typanbieters. Verwenden Sie diesen Namen für Verweise auf den Typ und die entsprechenden API-Ressourcen.
  • Deskriptordokument: Die URL des Deskriptordokuments für diesen Typ. Zu den unterstützten Dokumenten gehören Google Discovery-Dokumente und OpenAPI 1.2-Spezifikationen.
  • Authentifizierung: Alle Anmeldedaten, die zur Authentifizierung für die API erforderlich sind. Sie können eine Basisauthentifizierung festlegen. Wenn Ihre API auf Google Endpoints oder Google Kubernetes Engine ausgeführt wird, genügen auch die Anmeldedaten des Projektdienstkontos zur Authentifizierung.
  • Erweiterte Optionen: Beliebige erweiterte Eingabezuordnungen oder API-Optionen.

Name

Der Name des Typanbieters; Sie verwenden diesen Namen, um in künftigen Konfigurationen und Vorlagen auf den Typ verweisen zu können. Wenn Sie beispielsweise einen Typanbieter mit dem Namen my-awesome-type-provider erstellt haben, können Sie ihn anschließend so in nachfolgenden Vorlagen verwenden:

resources:
  name: a-deployment
  type: my-project/my-awesome-type-provider:some-collection
  properties:
  …

Dabei ist my-project die ID des Projekts, zu dem der Typ gehört, und some-collection der Pfad zur API-Ressource, die Sie erstellen.

Deskriptordokument

Das Deskriptordokument für einen Typanbieter kann entweder eine Spezifikation nach OpenAPI 1.2 oder 2.0 oder ein Google Discovery-Dokument sein. Sie finden das Google Discovery-Dokument für die Compute Engine Beta API beispielsweise unter dieser URL:

https://content.googleapis.com/discovery/v1/apis/compute/beta/rest

Hier finden Sie eine vollständige Liste der Google Discovery-Dokumente.

OpenAPI 1.2- und OpenAPI 2.0-Dokumente sind ebenfalls zulässig.

Authentifizierung

Wenn Ihre API eine Authentifizierung erfordert, können Sie hier die Authentifizierungsdetails angeben. Deployment Manager unterstützt Anmeldedaten für eine Basisauthentifizierung wie einen Nutzernamen und ein Passwort. Für Google Kubernetes Engine und Google Cloud Endpoints können Sie auch mit dem Authorization-Header ein Zugriffstoken aus dem Dienstkonto des Projekts bereitstellen.

Um eine Basisauthentifizierung festzulegen, geben Sie den Nutzernamen und das Passwort im Abschnitt credentials an:

credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Sie müssen den Nutzernamen und das Passwort nur angeben, wenn Sie einen Typanbieter zum ersten Mal erstellen.

Wenn Sie einen Cluster auf Google Kubernetes Engine ausführen, können Sie den Cluster als Typanbieter hinzufügen und über Deployment Manager auf die Kubernetes API zugreifen. Dies setzt voraus, dass Sie den Cluster in dem Projekt ausführen, in dem Sie auch Deployment Manager verwenden. In diesem Szenario können Sie das OAuth 2.0-Zugriffstoken des Google APIs-Dienstkontos des Projekts abrufen und im Authorization-Header angeben. Anders als oben für den Abschnitt "credentials" beschrieben, müssen Sie das Token als Eingabezuordnung wie folgt in Ihrer Anfrage angeben:

- fieldName: Authorization
  location: HEADER
  value: >
    $.concat("Bearer ", $.googleOauth2AccessToken())

Die googleOauth2AccessToken()-Methode ruft automatisch ein Zugriffstoken ab, wenn der Nutzer diesen Typanbieter aufruft. Ein vollständiges Beispiel finden Sie im Beispiel für GKE-Cluster und Typ.

Sie können dasselbe Verfahren für die Authentifizierung bei Google Cloud Endpoints verwenden.

Erweiterte Typoptionen

Manche APIs weisen möglicherweise Besonderheiten auf, die es für Deployment Manager schwierig machen, alle Eigenschaften der API in Deployment Manager zuzuordnen. In einem idealen Szenario liefern Sie ein Deskriptordokument und Deployment Manager ermittelt automatisch die API-Anfragepfade und die relevanten API-Eigenschaften ohne zusätzlichen Arbeitsaufwand für Sie. Bei komplexeren APIs interpretiert Deployment Manager zwar den Großteil der API richtig, aber es kann sein, dass Sie nicht offensichtliches API-Verhalten in Form von Eingabezuordnungen festlegen müssen.

Weitere Informationen zu Eingabezuordnungen finden Sie unter Erweiterte API-Optionen festlegen.

Typanbieter erstellen

Um einen Typanbieter zu erstellen, stellen Sie eine Anfrage an Deployment Manager mit einer Anfragenutzlast, die den Namen des gewünschten Typanbieters, die Deskriptor-URL und alle erforderlichen Anmeldedaten zur Authentifizierung enthält.

gcloud

Zum Erstellen eines Typanbieters mit dem gcloud-Tool verwenden Sie den Befehl type-providers create:

gcloud beta deployment-manager type-providers create [TYPE_PROVIDER_NAME] --descriptor-url=[URL]

wobei

  • [TYPE_PROVIDER_NAME] ist der Name, den Sie diesem Typ geben möchten.
  • [URL] ist die vollständig qualifizierte URL für das Deskriptordokument, das diesen Typ unterstützt. Beispiel:

    http://petstore.swagger.io/v2/swagger.json
    

Wenn Sie Anmeldedaten zur Authentifizierung oder erweiterte API-Optionen angeben möchten, können Sie eine in YAML geschriebene Datei mit API-Optionen erstellen und diese mit dem Flag --api-options-file bereitstellen. Diese Datei könnte wie folgt aussehen:

collectionOverrides:
- collection: /emailAddresses/v1beta/people
  options:
    inputMappings:
    - methodMatch: ^create$
      fieldName: emailAddress.displayName
      value: $.resource.properties.displayName
      location: BODY
    - methodMatch: ^update$
      fieldName: displayName
      value: $.resource.properties.displayName
      location: PATH
    virtualProperties: |
      schema: http://json-schema.org/draft-04/schema#
      type: object
      properties:
        displayName:
          type: string
      required:
      - displayName
credential:
  basicAuth:
    user: [USERNAME]
    password: [PASSWORD]

Der gcloud-Befehl wäre:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url]

API

Um einen Basistyp in der API zu erstellen, stellen Sie eine POST-Anfrage, die die descriptorUrl und optionale Konfigurationsoptionen im Anfragetext enthält. Beispiel:

POST https://www.googleapis.com/deploymentmanager/v2beta/projects/[PROJECT_ID]/global/typeProviders

{ "description":"",
  "descriptorUrl":"https://www.example.com/api/v1beta1.json",
  "name":"my-type-provider",
  "collectionOverrides":[
    {
      "collection":"emailAddresses/v1beta/people",
      "options":{
        "inputMappings":[
          {
            "fieldName":"emailAddress.displayName",
            "location":"BODY",
            "methodMatch":"^create$",
            "value":"$.resource.properties.displayName"
          },
          {
            "fieldName":"displayName",
            "location":"PATH",
            "methodMatch":"^update$",
            "value":"$.resource.properties.displayName"
          }
        ],
        "virtualProperties":"schema: http://json-schema.org/draft-04/schema#\ntype: object\nproperties:\n  displayName:\n    type: string\nrequired:\n- displayName\n"
      }
    }
  ],
  "credential":{
    "basicAuth":{
      "password":"example-password",
      "user":"example-user"
    }
  }
}

Weitere Informationen finden Sie in der Dokumentation zur Methode insert.

Typanbieter testen

So überprüfen Sie, ob Ihr Typanbieter wie erwartet funktioniert:

  1. Rufen Sie Ihren neuen Typanbieter in einer Konfiguration auf.
  2. Stellen Sie jede Sammlung bereit, die vom Typanbieter zur Verfügung gestellt wird, um zu gewährleisten, dass die API wie erwartet funktioniert. Eine Sammlung ist eine API-Ressource des angegebenen Typanbieters.
  3. Führen Sie eine Aktualisierung für jede Sammlung aus.
  4. Löschen Sie alle Sammlungen.

Wenn ein Nutzer einen Typ von Ihrem Typanbieter instanziiert, stellt er faktisch eine Anfrage an Deployment Manager und nicht explizit an die zugrunde liegende API. Deployment Manager erstellt wiederum die Anfrage mit den bereitgestellten Informationen, um im Namen des Nutzers eine Anfrage an die API zu senden. Wenn Probleme auftreten, liegt dies meistens daran, dass Deployment Manager die API-Attribute nicht automatisch erkennen kann. Manche APIs erfordern beispielsweise Eigenschaften, die nur aus einer API-Antwort extrahiert werden können. Andere APIs verwenden denselben Feldnamen je nach Vorgang mit unterschiedlichen Werten. In diesen Fällen müssen Sie Deployment Manager ausdrücklich mitteilen, wie diese Szenarien zu behandeln sind.

Wenn Ihre API eines dieser Merkmale aufweist, verwenden Sie Eingabezuordnungen, um die Mehrdeutigkeit für Deployment Manager zu beseitigen.

Nächste Schritte

© 2016 Swagger. Alle Rechte vorbehalten.