Provision API-Hub mit der Befehlszeile nutzen

Diese Seite gilt für Apigee und Apigee Hybrid.

In diesem Abschnitt wird beschrieben, wie Sie den API-Hub über die Befehlszeile bereitstellen.

Zusammenfassung der Schritte

Dazu sind folgende Schritte erforderlich:

Prüfen Sie, ob Sie die Voraussetzungen für API-Hub erfüllen.
Schritt 1: APIs aktivieren. Für Apigee müssen Sie mehrere Google Cloud APIs aktivieren.
Schritt 2: Umgebungsvariablen definieren. Umgebungsvariablen sorgen beim Ausführen von Befehlen für Konsistenz.
Schritt 3: Dienstkonto und CMEK erstellen. Dieses Dienstkonto wird von den Google Cloud-Clientbibliotheken zur Authentifizierung bei Google Cloud APIs verwendet. Da Informationen zu internen APIs als vertraulich angesehen werden können, erfordert Apigee einen CMEK zum Verschlüsseln und Entschlüsseln (Schützen) inaktiver Daten. Der CMEK muss sich in derselben Region wie der Instanzstandort befinden.
Schritt 4: Instanz erstellen. In einer Instanz werden Ihr Projekt und die zugehörigen Dienste gespeichert.
Instanzstatus prüfen (optional). Das Erstellen einer Instanz kann etwas dauern; mit diesem Befehl können Sie den Status prüfen.
Instanz löschen (optional). Verwenden Sie diesen Befehl, wenn Sie eine Instanz entfernen müssen.
Vorgangsstatus prüfen (optional). Mit diesem Befehl können Sie den Status eines Vorgangs mit langer Ausführungszeit prüfen.

Schritt 1: APIs aktivieren

Um den API-Hub zu verwenden, müssen Sie die folgenden APIs für das Projekt aktivieren:

Apigee Registry API: Der API-Hub interagiert mit API Registry, um die APIs Ihrer Organisation aufzurufen und zu verwalten.
Cloud Key Management Service (KMS) API: Ermöglicht Kunden die Verwaltung von Verschlüsselungsschlüsseln und die Ausführung kryptografischer Vorgänge mit diesen Schlüsseln.
Service Usage API: Aktiviert Dienste, die Dienstnutzer in der Google Cloud Platform verwenden möchten, listet die verfügbaren oder aktivierten Dienste auf oder deaktiviert Dienste, die von Dienstnutzern nicht mehr verwendet werden.

Sie können die APIs über die Benutzeroberfläche der Google Cloud Console oder die Befehlszeile aktivieren.

Console

Um die APIs über die Benutzeroberfläche zu aktivieren, führen Sie die folgenden Schritte in der Google Cloud Console aus:

Aktivieren Sie die Apigee Registry API:

Zur Apigee Registry API

Klicken Sie auf Aktivieren.

Google Cloud aktiviert die API für Ihr Google Cloud-Projekt.
Aktivieren Sie die Cloud Key Management Service (KMS) API:

Zur Aktivierung der Cloud KMS API

Klicken Sie auf Aktivieren.

Google Cloud aktiviert die API für Ihr Google Cloud-Projekt.
Service Usage API aktivieren:
Zur Aktivierung der Service Usage API

Klicken Sie auf Aktivieren.

Google Cloud aktiviert die API für Ihr Google Cloud-Projekt.
So prüfen Sie, ob die APIs aktiviert sind:
Zur Aktivierung von APIs und Dienste

Die soeben hinzugefügten APIs werden in der Liste der aktivierten APIs angezeigt:
- Apigee Registry API
- Cloud Key Management Service (KMS) API
- Service Usage API

gcloud

Führen Sie folgenden Befehl aus:

gcloud services enable \
    apigeeregistry.googleapis.com \
    cloudkms.googleapis.com \
    serviceusage.googleapis.com --project=PROJECT_ID

Dabei ist PROJECT_ID der Name Ihres Google Cloud Console-Projekts.

(Optional) Rufen Sie zum Prüfen Ihrer Arbeit mit dem Befehl services list alle aktivierten APIs auf:
```
gcloud services list
```
In der Antwort werden alle aktivierten Dienste angezeigt, einschließlich der APIs, die Sie gerade aktiviert haben.

Schritt 2: Umgebungsvariablen definieren

Die Verwendung von Umgebungsvariablen garantiert die Konsistenz und macht es einfacher, der Dokumentation in späteren Schritten zu folgen.

Definieren Sie folgende Umgebungsvariablen und ersetzen Sie die dynamischen Variablen durch Ihre tatsächlichen Werte:
```
export TOKEN=$(gcloud auth print-access-token)

# ----- Set key_ring_name and key_name to values that will help you identify the API hub encryption key in future. -----
export KEY_RING_NAME=YOUR_KEY_RING_NAME
export KEY_NAME=YOUR_KEY_NAME

export PROJECT_ID=YOUR_PROJECT_ID
export RUNTIME_LOCATION=YOUR_RUNTIME_LOCATION

# -----If you already have a CMEK, define this environment variable-----
export CMEK_KEY_ID=YOUR_CMEK_KEY_ID
```
Wobei:
- TOKEN ist das Token, das Ihre Aufrufe an die Apigee Registry APIs authentifiziert und autorisiert. Es sollte in Authentifizierungs-Headern als Inhabertoken übergeben werden. Beachten Sie, dass das Token nach einer gewissen Zeit abläuft. Wenn dies der Fall ist, können Sie es einfach mit demselben Befehl neu generieren. Weitere Informationen finden Sie auf der Referenzseite für den Befehl print-access-token.
- KEY_RING_NAME ist der Name des Schlüsselbunds, mit dem Sie Ihren Verschlüsselungs-Schlüsselbund identifizieren.
- KEY_NAME ist der Name des Schlüssels, mit dem Sie Ihren API-Hub-Verschlüsselungsschlüssel identifizieren.
- PROJECT_ID ist die Cloud-Projekt-ID, die Sie als eine der Voraussetzungen erstellt haben.
- RUNTIME_LOCATION ist der physische Standort für die Apigee Registry-Instanz, die Sie später erstellen. Der CMEK-Schlüssel muss sich in derselben Region wie der Laufzeitstandort befinden.
  
  Hinweis:
  Verwenden Sie für RUNTIME_LOCATION unbedingt einen Regionsnamen und keinen Zonennamen. Beispielsweise ist us-west1 ein Regionsname, während us-west1-a eine Zone in der Region ist. Siehe auch Region oder Zone identifizieren.
  
  Eine Liste der verfügbaren Laufzeitstandorte finden Sie unter Apigee-Standorte.
- CMEK_KEY_ID ist die Schlüssel-ID Ihres vom Kunden verwalteten Verschlüsselungsschlüssels. Die Schlüsselrotation wird derzeit nicht unterstützt.
  
  Die Schlüssel-ID hat die folgende Syntax (ähnlich einem Dateipfad):
```
projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```
(Optional) Um Ihre Arbeit zu testen, rufen Sie die soeben festgelegten Werte ab. Wenn Sie in Ihren Befehlen eine Variable verwenden möchten, stellen Sie dem Variablennamen ein Dollarzeichen ($) voran.
```
echo $TOKEN
echo $KEY_RING_NAME
echo $KEY_NAME
echo $PROJECT_ID
echo $RUNTIME_LOCATION

# -----If you already have a CMEK-----
echo $CMEK_KEY_ID
```

Schritt 3: Dienstkonto und CMEK erstellen

In diesem Abschnitt wird beschrieben, wie Sie ein Dienstkonto und einen Verschlüsselungs-Schlüsselbund nebst Schlüssel erstellen.

Erstellen Sie für Ihr Projekt ein produkt- und projektspezifisches Apigee-Registry-Dienstkonto:

Hinweis: Sie können diesen Befehl mehrmals ausführen, auch wenn das Dienstkonto bereits erstellt wurde.
```
gcloud beta services identity create --service=apigeeregistry.googleapis.com --project=$PROJECT_ID
```
Das zurückgegebene Dienstkonto sieht in etwa so aus:
```
service-755582297973@gcp-sa-apigeeregistry.iam.gserviceaccount.com
```
Fügen Sie das erstellte Dienstkonto in eine Variable ein:
```
export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT
```
Erstellen Sie einen CMEK mithilfe von KMS. Führen Sie dazu die folgenden Schritte aus oder verwenden Sie einen vorhandenen KMS-Schlüssel. Der CMEK-Schlüssel muss sich in derselben Region wie der Laufzeitstandort befinden.
1. Schlüsselbund erstellen:
```
gcloud kms keyrings create $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
2. Schlüssel erstellen:
```
gcloud kms keys create $KEY_NAME \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --purpose "encryption" \
  --project $PROJECT_ID
```
3. Prüfen, ob der Schlüssel erstellt wurde. Die Erstellung des Schlüssels kann einige Minuten dauern. Wenn dieser Befehl eine leere Liste zurückgibt, warten Sie und versuchen Sie es noch einmal. Wenn der Schlüssel angezeigt wird, können Sie mit dem nächsten Schritt fortfahren:
```
gcloud kms keys list \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
  Der zurückgegebene Schlüssel sieht in etwa so aus:
```
projects/my-project/locations/us-west1/keyRings/my-key-ring-name/cryptoKeys/my-key-name
```
4. Den erstellten Schlüssel in eine Variable einfügen:
```
export CMEK_KEY_ID=projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```

Gewähren Sie dem Dienstkonto die Berechtigung für den CMEK:

gcloud kms keys add-iam-policy-binding $KEY_NAME \
  --location $RUNTIME_LOCATION \
  --keyring $KEY_RING_NAME \
  --member serviceAccount:$SERVICE_ACCOUNT \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project $PROJECT_ID

Prüfen Sie, ob Ihr Dienstkonto die Berechtigung roles/cloudkms.cryptoKeyEncrypterDecrypter für den CMEK hat.
```
gcloud kms keys get-iam-policy $CMEK_KEY_ID
```

Schritt 4: Instanz erstellen

In diesem Abschnitt erstellen Sie eine einzelne Instanz des API-Hubs. Es kann nur eine Instanz pro Projekt vorhanden sein.

Beispielanfrage

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances?instance_id=default \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "config": {
      "cmek_key_name": "'"$CMEK_KEY_ID"'"
  }
}'

Beispielantwort

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Häufige Fehler – fehlerhafte Eingabedaten

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`Instance is a singleton, and instance_id must be set to "default".`
Mögliche Ursache:	`instance_id` ist auf einen anderen Wert als `default` eingestellt.
Lösung:	Verwenden Sie `default` als `instance_id`.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`global is not a supported location to create Instance.`
Mögliche Ursache:	`global` wurde als Speicherort festgelegt.
Lösung:	Verwenden Sie einen der oben aufgeführten unterstützten Laufzeitstandorte.

HTTP-Statuscode:	`401 Unauthorized`
Fehlermeldung:	`Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.`
Mögliche Ursache:	Ungültiges Authentifizierungstoken.
Lösung:	Das Anfragetoken ist möglicherweise falsch formatiert oder abgelaufen. Generieren Sie das Authentifizierungstoken neu, indem Sie `token="$(gcloud auth print-access-token)"` ausführen und `Authorization: Bearer ${token}` als Header übergeben.

HTTP-Statuscode:	`403 PERMISSION_DENIED`
Fehlermeldung:	`Location RUNTIME_LOCATION is not found or access is unauthorized.`
Mögliche Ursache:	Es wurde ein nicht unterstützter Standort festgelegt.
Lösung:	Verwenden Sie einen der oben aufgeführten unterstützten Laufzeitstandorte.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`Instance.config.cmek_key_name must be provided to create Instance.`
Mögliche Ursache:	`cmek_key_name` wird in den Daten nicht bereitgestellt.
Lösung:	Geben Sie den CMEK-Namen an. Eine ausführlich Anweisung finden Sie unter Dienstkonto und CMEK erstellen.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`Invalid key format: a valid key should be in the form of projects/PROJECT/locations/us-central1/keyRings/KEYRING/cryptoKeys/CRYPTOKEY.`
Mögliche Ursache:	`cmek_key_name` ist falsch formatiert.
Lösung:	Korrigieren Sie das Schlüsselformat.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`CMEK key location needs to match the location of instance creation.`
Mögliche Ursache:	CMEK befindet sich an einem anderen Standort.
Lösung:	Korrigieren Sie den CMEK-Standort.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`Apigee Registry service account must have roles/cloudkms.cryptoKeyEncrypterDecrypter permission on the CMEK key.`
Mögliche Ursache:	Dem Apigee-Dienstkonto fehlt die Berechtigung für den CMEK. Beachten Sie, dass wir nur feststellen können, dass das Dienstkonto nicht die notwendige Berechtigung hat. Es ist wahrscheinlich, dass der Schlüssel überhaupt nicht vorhanden ist. Das wissen wir allerdings nicht.
Lösung:	Prüfen Sie, ob der Schlüssel vorhanden ist und das Apigee Registry-Dienstkonto die erforderliche Berechtigung für den Schlüssel hat.

Häufige Fehler – Fehlerstatus

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	Wenn die Instanz aktiv ist: `Instance is ACTIVE at SOME_LOCATION. It cannot be created again.` Wenn die Instanz einen anderen Status als "Aktiv" hat: `Instance has state STATE at SOME_LOCATION. It cannot be created.`
Mögliche Ursache:	Diese API wurde aufgerufen, während bereits eine Instanz vorhanden war oder an einem bestimmten Standort erstellt wurde.
Lösung:	Ignorieren Sie den Fehler, falls diese API versehentlich ausgelöst wurde. Wenn es sich um einen legitimen Aufruf handelt und Sie wirklich eine Instanz an diesem Standort erstellen möchten, rufen Sie zuerst `DeleteInstance` am aktuellen Instanzstandort auf.

Instanz abrufen

In diesem Abschnitt wird beschrieben, wie Sie Details (Region, Status usw.) zur mit Ihrem Projekt verknüpften API-Hub-Laufzeitinstanz abrufen.

Beispielanfrage

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Beispielantwort – Instanzerstellung läuft

{
  "name": "projects/my-project/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:32:14.944703257Z",
  "state": "CREATING",
  "stateMessage": "Creating instance...\nDetails: projects/PROJECT_ID/locations/RUNTIME_LOCATION/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
  }
}

Beispielantwort – Instanzerstellung abgeschlossen

{
  "name": "projects/myproject/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:56:31.087709218Z",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/my-project/locations/us-central1/keyRings/apihub-key-ring/cryptoKeys/apihub-key"
  },
  "state": "ACTIVE",
  "stateMessage": "Instance is active and ready to use."
}

Häufige Fehler

HTTP-Statuscode:	`404 Not Found`
Fehlermeldung:	`Resource was not found.`
Mögliche Ursache:	Diese API wurde an einem Ort aufgerufen, an dem keine Instanz vorhanden ist.
Lösung:	Rufen Sie die `CreateInstance`-API auf, bevor Sie die `GetInstance`-API an dem Standort aufrufen, an dem Sie die Instanz erstellen möchten. Wenn die Instanz erstellt wurde, Sie den Standort jedoch nicht kennen, rufen Sie die `CreateInstance`-API an einem beliebigen Standort auf. Dies schlägt mit einer Meldung fehl, die einen Hinweis auf den Instanzstandort enthält.

Instanz löschen

In diesem Abschnitt wird beschrieben, wie Sie eine Instanz löschen.

Hinweis: DeleteInstance ist ein Vorgang mit langer Ausführungszeit. Er dauert 10 bis 15 Sekunden. Beim Aufruf von DeleteInstance wird eine Vorgangs-ID zurückgegeben. Rufen Sie GetOperation mit der Vorgangs-ID auf, um den Status des LRO zu prüfen.

Beispielanfrage

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

Beispielantwort

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": false
}

Häufige Fehler

HTTP-Statuscode:	`404 Not Found`
Fehlermeldung:	`Resource was not found.`
Mögliche Ursache:	Diese API wurde an einem Ort aufgerufen, an dem keine Instanz vorhanden ist.
Lösung:	Rufen Sie `DeleteInstance` nur an dem Standort auf, an dem die Instanz `ACTIVE` oder `FAILED` ist.

HTTP-Statuscode:	`400 Bad Request`
Fehlermeldung:	`Instance must be ACTIVE or FAILED to be deleted. Current state: STATE.`
Mögliche Ursache:	Diese API wurde an einem Standort aufgerufen, an dem der Instanzstatus nicht `ACTIVE` oder `FAILED` ist.
Lösung:	Rufen Sie `DeleteInstance` nur an dem Standort auf, an dem die Instanz `ACTIVE` oder `FAILED` ist.

Vorgang abrufen

In diesem Abschnitt wird beschrieben, wie Sie den Vorgangsstatus prüfen. Wenn Vorgänge sehr lange dauern, gibt die API eine Vorgangs-ID zurück. Beim Aufrufen von GetOperation mithilfe der Vorgangs-ID wird der Vorgangsstatus zurückgegeben.

Beispielanfrage

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/operations/OPERATION_ID \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Dabei ist OPERATION_ID ein Wert, der für LROs zurückgegeben wird (siehe Instanz erstellen). Er hat das Format operation-1650479361714-5dd1a2c1068bf-464fac6b-18eeb734.

Beispielantwort – Instanzerstellung läuft

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Beispielantwort – Instanzerstellung abgeschlossen

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "endTime": "2022-03-11T08:56:31.069701960Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.Instance",
    "name": "projects/my-project/locations/us-central1/instances/default",
    "createTime": "2022-03-11T08:32:14.944703257Z",
    "updateTime": "2022-03-11T08:56:31.069701960Z",
    "config": {
      "location": "us-central1",
      "cmekKeyName": ""projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
    },
    "state": "ACTIVE",
    "stateMessage": "Instance is active and ready to use."
  }
}

Beispielantwort – Instanzlöschung abgeschlossen

{
  "name": "projects/my-project/locations/us-east1/operations/operation-1647669637561-5da8bfb743b86-4af586a4-83c04472",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-19T06:00:38.046462309Z",
    "endTime": "2022-03-19T06:01:01.382751041Z",
    "target": "projects/my-project/locations/us-east1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Nächste Schritte

Unter Nächste Schritte finden Sie einige Tipps zu den ersten Schritten mit dem API Hub.