API als Typanbieter hinzufügen

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

Ein Typanbieter zeigt alle Ressourcen einer Drittanbieter-API in Deployment Manager als Basistypen an, 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, solange die API über eine OpenAPI-Spezifikation (früher als Swagger© bezeichnet) oder ein Google Discovery-Dokument verfügt. 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.

Vorbereitung

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

Komponenten eines Typenanbieters

Ein Typanbieter besteht aus:

  • Name: Gewünschter Name des Typanbieters. Verwenden Sie diesen Namen für Referenzen auf diesen 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 oder OpenAPI 1.2-Spezifikationen.
  • Authentifizierung: Alle Anmeldedaten für die Authentifizierung der API. 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. Beispiel: Wenn Sie einen Typanbieter erstellt und my-awesome-type-provider genannt haben, können Sie diesen in nachfolgenden Vorlagen wie folgt als Referenz verwenden:

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

Wobei my-project die Projekt-ID ist, zu der der Typ gehört, und some-collection der Pfad zu der API-Ressource ist, die Sie erstellen möchten.

Deskriptordokument

Das Deskriptordokument für einen Typanbieter kann entweder eine OpenAPI 1.2 oder 2.0-Spezifikation 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.

Auch OpenAPI- und OpenAPI 2.0-Dokumente sind zulässig.

Authentifizierung

Wenn Ihre API eine Authentifizierung erfordert, können Sie hier die Authentifizierungsdetails angeben. Deployment Manager unterstützt die Anmeldedaten für eine Basisauthentifizierung, z. B. Nutzername und Passwort. Wenn Sie Google Kubernetes Engine und Google Cloud Endpoints verwenden, können Sie den Authorization-Header dazu verwenden, ein Zugriffstoken aus dem Projektdienstkonto bereitzustellen.

Wenn Sie die Basisauthentifizierung verwenden, legen Sie den Nutzernamen und das Passwort im Bereich credentials fest:

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

Sie müssen den Nutzernamen und das Passwort nur angeben, wenn Sie zum ersten Mal einen Typanbieter 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 demselben Projekt ausführen, in dem Sie Deployment Manager verwenden. In diesem Szenario können Sie das OAuth 2.0-Zugriffstoken des Google API-Dienstkontos Ihres Projekts abrufen und das Zugriffstoken im Authorization-Header bereitstellen. Anders als oben für den Abschnitt "credentials" beschrieben, müssen Sie diese Anmeldeinformationen als Eingabezuordnung wie folgt in Ihrer Anfrage angeben:

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

Die googleOauth2AccessToken()-Methode erhält automatisch ein Zugriffstoken, wenn der Benutzer diesen Typanbieter aufruft. Ein vollständiges Beispiel finden Sie unter GKE-Cluster und Typbeispiel.

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.

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

Um einen Typanbieter mit dem gcloud-Tool zu erstellen, verwenden Sie den Befehl type-providers create:

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

Dabei gilt Folgendes:

  • [TYPE_PROVIDER_NAME] ist der Name, den Sie diesem Typ geben möchten.
  • [URL] ist die vollständig qualifizierte URL zu dem 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 API-Optionsdatei in YAML erstellen und diese mit dem Flag --api-options-file angeben. 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 im Anforderungstext descriptorUrl und optionale Konfigurationsoptionen 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, die vom Typanbieter geliefert wird, bereit, um sicherzustellen, dass die API wie erwartet funktioniert. Eine Sammlung ist eine API-Ressource aus dem angegebenen Typanbieter.
  3. Führen Sie für jede Sammlung eine Aktualisierung durch.
  4. Löschen Sie alle Sammlungen.

Wenn ein Nutzer einen Typ aus Ihrem Typanbieter instanziiert, stellt dieser eine Anfrage an Deployment Manager und nicht direkt an die zugrunde liegende API. Stattdessen erstellt Deployment Manager wiederum eine Anfrage mit den bereitgestellten Informationen, um im Namen des Nutzers eine Anfrage an die API zu stellen. Die häufigsten Probleme treten auf, weil Deployment Manager die API-Eigenschaften 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.

Weitere Informationen

© 2016 Swagger. Alle Rechte vorbehalten.

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager-Dokumentation