API als Typanbieter hinzufügen

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

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

Um eine nicht automatisch von Google mit Deployment Manager bereitgestellte API zu verwenden, müssen Sie die API als Typanbieter hinzufügen. Sie können eine beliebige API als Typanbieter verwenden, wenn die API eine OpenAPI-Spezifikation (früher Swagger^© genannt) oder ein Google Discovery-Dokument hat.

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: Wenn Sie eine Beispiel-API mit Google Cloud Endpoints bereitstellen möchten, folgen Sie der Cloud Endpoints-Kurzanleitung.

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 dieser Anleitung 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 für die API erforderlichen Authentifizierungsdaten. Sie können eine Basisauthentifizierung bestimmen. Wenn Ihre API auf Google Endpoints oder Google Kubernetes Engine (GKE) ausgeführt wird, genügen 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, darunter Nutzernamen und 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.

Zur Bestimmung der Basisauthentifizierung geben Sie Nutzernamen und 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.

Wird in dem Projekt, in dem Sie Deployment Manager verwenden, ein Cluster in Google Kubernetes Engine (GKE) ausgeführt, so können Sie den Cluster als Typanbieter hinzufügen und mit Deployment Manager auf die GKE API zugreifen. In diesem Szenario können Sie das OAuth 2.0-Zugriffstoken des Google API-Dienstkontos des Projekts abrufen und im Authorization-Header bereitstellen. Anders als im vorherigen Abschnitt zu den Anmeldedaten müssen Sie dies in Ihrer Abfrage als Eingabezuordnung 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.

Optional: Benutzerdefinierter Zertifizierungsstellenstamm

Wenn Sie Deployment Manager eine API als Typanbieter hinzufügen möchten und der HTTPS-Endpunkt der API zur Verschlüsselung der Verbindung ein Zertifikat verwendet, das nicht von einer öffentlich vertrauenswürdigen Zertifizierungsstelle (CA, Certification Authority) bereitgestellt wird, können Sie die API Ihrer Konfiguration wie im folgenden Beispiel hinzufügen:

customCertificateAuthorityRoots:
- $(ref.my-gke-cluster.masterAuth.clusterCaCertificate)

Dabei ist my-gke-cluster der von Ihnen verwendete GKE-Cluster. Ein detailliertes Beispiel finden Sie im Beispiel für einen GKE-Anbietercluster.

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

Verwenden Sie den Befehl type-providers create, um einen Typanbieter mit der gcloud CLI zu erstellen:

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

Dabei gilt:

[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 so 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]

Wenn Sie sich über eine benutzerdefinierte Zertifizierungsstelle authentifizieren möchten, können Sie die Zertifizierungsstelle wie im folgenden Beispiel als Flag dem Befehl gcloud hinzufügen:

gcloud beta deployment-manager type-providers create [TYPE_NAME] --api-options-file=[FILE_NAME] \
    --descriptor-url [url] \
    --custom-certificate-authority-roots=[CA_NAME]

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:

Rufen Sie Ihren neuen Typanbieter in einer Konfiguration auf.
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.
Führen Sie eine Aktualisierung für jede Sammlung aus.
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

Typanbieter aufrufen
Typanbieter mit anderen Projekten teilen
Weitere Informationen zu Typen
Informationen zu Konfiguration erstellen lesen
Bereitstellung erstellen
Weitere Informationen zu erweiterten API-Optionen