Von Cloud Endpoints verwaltete API bereitstellen

Von Cloud Endpoints verwaltete API bereitstellen

In dieser Kurzanleitung wird das Bereitstellen einer von Endpoints verwalteten Beispiel-API Schritt für Schritt beschrieben. Der Beispielcode enthält:

• eine REST API, die Sie abfragen können, um den Namen eines Flughafens anhand seines dreistelligen IATA-Codes zu ermitteln,
• ein Skript zum Hochladen der API-Konfiguration in Endpoints und
• ein Skript zum Bereitstellen eines Back-Ends der flexiblen App Engine-Umgebung, um die Beispiel-API zu hosten.

Nachdem Sie Anfragen an die Beispiel-API gesendet haben, können Sie die Endpoints-Aktivitätsgrafiken und die Google Cloud Observability-Protokolle in der Google Cloud Console ansehen. Mit diesen Tools lassen sich die APIs beobachten und Einblicke in deren Verwendung gewinnen.

In dieser Kurzanleitung werden die Konfigurationsschritte mithilfe von Skripts vereinfacht, damit Sie die Aktivitätsgrafiken und Logs schnell in Aktion erleben können. Wenn Sie die Vorgehensweise zum Konfigurieren und Bereitstellen einer Beispiel-API kennenlernen möchten, wählen Sie eine Anleitung für eines der API-Frameworks aus:

• Cloud Endpoints für OpenAPI: Anleitungen
• Cloud Endpoints für gRPC: Anleitungen
• Cloud Endpoints Frameworks: Anleitungen

Vorbereitung

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

Cloud Shell starten

1. Achten Sie in der Google Cloud Console darauf, dass Sie sich im Projekt befinden, das Sie für die Beispiel-API verwenden möchten.

2. Öffnen Sie Cloud Shell.

   Cloud Shell öffnen

   Im unteren Bereich der Google Cloud Console wird ein neuer Frame mit einer Cloud Shell-Sitzung und einer Befehlszeilen-Eingabeaufforderung geöffnet. Das Initialisieren der Sitzung kann einige Sekunden dauern.

   

3. Aktualisieren Sie bei Verwendung eines vorhandenen Projekts alle installierten gcloud-Komponenten auf die neueste Version:

   gcloud components update
   

Hinweis: Wenn Sie auf einem Linux- oder MacOS-Computer arbeiten und diese Kurzanleitung mit Ihrer lokalen Shell ausführen möchten, laden Sie die Google Cloud CLI herunter. Führen Sie dann die Schritte dieser Kurzanleitung über die lokale Befehlszeile anstelle von Cloud Shell aus.

Beispielcode abrufen

1. Geben Sie in Cloud Shell folgenden Befehl ein, um die Beispiel-API und die Skripts abzurufen:

   git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
   

2. Wechseln Sie zu dem Verzeichnis, das den Beispielcode enthält:

   cd endpoints-quickstart
   

Endpoints-Konfiguration bereitstellen

Zum Veröffentlichen einer REST API in Endpoints ist eine OpenAPI-Konfigurationsdatei erforderlich, in der die API beschrieben wird. Die Beispiel-API wird mit einer vorkonfigurierten OpenAPI-Datei namens openapi.yaml bereitgestellt.

Endpoints verwendet Service Management, einen Infrastrukturdienst von Google Cloud, um APIs und Dienste zu erstellen und zu verwalten. Damit Sie eine API mit Endpoints verwalten können, müssen Sie die OpenAPI-Konfigurationsdatei der API in Service Management bereitstellen.

So stellen Sie die Endpoints-Konfiguration bereit:

1. Geben Sie in Cloud Shell im Verzeichnis endpoints-quickstart Folgendes ein:

   cd scripts
   

2. Führen Sie das folgende im Beispiel enthaltene Skript aus:

   ./deploy_api.sh
   

Endpoints verwendet zur Identifikation des Dienstes das Feld host in der OpenAPI-Konfigurationsdatei. Das Skript deploy_api.sh legt die ID Ihres Google Cloud-Projekts als Teil des im Feld host konfigurierten Namens fest. Wenn Sie eine OpenAPI-Konfigurationsdatei für Ihren eigenen Dienst erstellen, müssen Sie dies manuell tun.

Das Skript stellt dann mit dem Befehl gcloud endpoints services deploy openapi.yaml die OpenAPI-Konfiguration in Service Management bereit.

Beim Erstellen und Konfigurieren des Dienstes gibt Service Management Informationen an die Google Cloud Console aus. Warnhinweise, die besagen, dass für die Pfade in openapi.yaml kein API-Schlüssel erforderlich ist, können Sie bedenkenlos ignorieren. Nach dem erfolgreichen Abschluss des Vorgangs wird eine Zeile wie die folgende mit der Dienstkonfigurations-ID und dem Dienstnamen angezeigt:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

Erforderliche Dienste werden aktiviert

Für Endpoints müssen mindestens die folgenden Google-Dienste aktiviert sein:

Name	Titel
servicecontrol.googleapis.com	Service Control API
servicemanagement.googleapis.com	Service Management API

In den meisten Fällen werden diese erforderlichen Dienste durch die Bereitstellung der Endpoints-Konfiguration aktiviert.

Prüfen Sie mit dem folgenden Befehl, ob die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie aktivieren:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Aktivieren Sie auch Ihren Endpoints-Dienst:

gcloud services enable YOUR-PROJECT-ID.appspot.com

Weitere Informationen zu den gcloud-Befehlen finden Sie unter gcloud-Dienste.

API-Backend bereitstellen

Sie haben jetzt die OpenAPI-Konfiguration in Service Management bereitgestellt, den Code für das API-Back-End jedoch noch nicht. Das im Beispiel enthaltene Skript deploy_app.sh erstellt eine flexible App Engine-Umgebung, in der das API-Back-End gehostet wird, und stellt dann die API in App Engine bereit.

API-Back-End bereitstellen:

• Führen Sie in Cloud Shell im Verzeichnis endpoints-quickstart/scripts das folgende Skript aus:

  ./deploy_app.sh
  

Das Skript führt den folgenden Befehl aus, um eine flexible App Engine-Umgebung in der Region us-central zu erstellen: gcloud app create --region="$REGION"

Das Erstellen des Back-Ends der flexiblen App Engine-Umgebung dauert einige Minuten. Nachdem die Anwendung erstellt wurde, sieht die Ausgabe so aus:

Success! The app is now created.

Als Nächstes führt das Skript den Befehl gcloud app deploy aus, um die Beispiel-API in App Engine bereitzustellen.

Die Ausgabe sieht so aus:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

Das Bereitstellen der API in App Engine dauert mehrere Minuten. Wenn die API erfolgreich in App Engine bereitgestellt wurde, sieht die Ausgabe so aus:

Deployed service [default] to [https://example-project.appspot.com]

Anfragen an die API senden

• Nach dem Bereitstellen der Beispiel-API können Sie in Cloud Shell Anfragen an diese senden. Führen Sie dazu folgendes Skript aus:

  ./query_api.sh
  

Das Skript zeigt zuerst den curl-Befehl an, mit dem eine Anfrage an die API gesendet wird, und dann das Ergebnis. Die Ausgabe sieht so aus:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

Die API erwartet den Abfrageparameter iataCode, für den ein gültiger IATA-Flughafencode wie SEA oder JFK festgelegt ist. Beispiel:

./query_api.sh JFK

Hinweis: Es kann einige Minuten dauern, bis App Engine erfolgreich reagiert. Wenn Sie eine Anfrage senden und der HTTP-Fehler 502, 503 oder ein anderer Serverfehler zurückgegeben wird, warten Sie eine Minute und wiederholen Sie dann die Anfrage.

Sie haben gerade eine API in Cloud Endpoints bereitgestellt und getestet!

Hinweis: Wenn Sie uns mitteilen möchten, was Ihnen an dieser Anleitung gefallen hat, können Sie uns gerne Feedback geben. Ihr Feedback hilft uns bei der Verbesserung dieser Anleitungen.
Wenn Sie eine Fehlermeldung erhalten, können Sie der Google-Gruppe google-cloud-endpoints beitreten und uns mitteilen, was schiefgegangen ist. Sie erhalten in dieser Gruppe Antworten von anderen Endpoints-Nutzern und Google-Entwicklern, die die Diskussion in der Gruppe verfolgen.

API-Aktivität verfolgen

Mit APIs, die mit Endpoints bereitgestellt werden, können Sie kritische Betriebsmesswerte in der Google Cloud Console überwachen und mit Cloud Logging Erkenntnisse zu Ihren Nutzern und zur Verwendung gewinnen.

1. Führen Sie in Cloud Shell das Skript zum Generieren von Traffic aus, um die Grafiken und Logs zu füllen:

   ./generate_traffic.sh
   

   Hinweis: Dieses Script generiert Anfragen in einer Schleife, bis nach fünf Minuten automatisch eine Zeitüberschreitung erfolgt. Wenn Sie das Skript früher beenden möchten, geben Sie Control+C in die Cloud Shell ein.

2. Sehen Sie sich in der Google Cloud Console die Aktivitätsgrafiken für Ihre API an.

   Endpoints-Dienste aufrufen

   Es kann etwas dauern, bis die Anfragen in den Grafiken widergespiegelt werden. Während Sie auf das Anzeigen der Daten warten:

   • Wenn die Seitenleiste "Berechtigungen" nicht geöffnet ist, klicken Sie auf +Berechtigungen. Im Bereich "Berechtigungen" können Sie steuern, wer Zugriff auf die API hat, und die Zugriffsebene festlegen.

   • Klicken Sie auf Bereitstellungsverlauf. Auf diesem Tab wird ein Verlauf Ihrer API-Bereitstellungen einschließlich der Bereitstellungszeit und der Person angezeigt, von der die Änderung vorgenommen wurde.

   • Klicken Sie auf Übersicht. Sie sehen den eingehenden Traffic. Nachdem das Skript zum Generieren von Traffic eine Minute lang ausgeführt wurde, enthält die Grafik Gesamtlatenz drei Zeilen (50., 95. und 98. Perzentil). Diese Daten liefern eine Schätzung der Antwortzeiten.

3. Scrollen Sie zur Tabelle unter den Grafiken und klicken Sie unter Links auf Logs ansehen für GET/airportName. Auf der Seite Log Explorer werden die Anfragelogs für die API angezeigt.

4. Cloud Shell öffnen

   Cloud Shell öffnen

5. Zum Beenden des Skripts geben Sie Control+C ein.

Kontingent zur API hinzufügen

Beta

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Mit Endpoints lassen sich Kontingente zum Steuern der Rate festlegen, mit der Anwendungen Ihre API aufrufen können. Kontingente eignen sich dazu, die API vor übermäßiger Nutzung durch einen einzelnen Client zu schützen.

1. Stellen Sie in Cloud Shell die Endpoints-Konfiguration bereit, die ein Kontingent hat:

   ./deploy_api.sh ../openapi_with_ratelimit.yaml
   

   Nachdem Sie eine aktualisierte Endpoints-Konfiguration bereitgestellt haben, wird diese innerhalb von einer Minute aktiviert.

2. Wechseln Sie in der Google Cloud Console zur Seite Anmeldedaten.

   Zur Seite "Anmeldedaten"

3. Klicken Sie auf Anmeldedaten erstellen und dann auf API-Schlüssel. Ein neuer API-Schlüssel wird auf dem Bildschirm angezeigt.

4. Klicken Sie auf Kopieren.

5. Geben Sie in Cloud Shell folgenden Befehl ein und ersetzen Sie YOUR_API_KEY durch den gerade erstellten API-Schlüssel:

   export API_KEY=YOUR_API_KEY
   

6. Senden Sie Ihrer API eine Anfrage mit dem soeben generierten API-Schlüssel.

   ./query_api_with_key.sh $API_KEY
   

   Die Ausgabe sieht etwa so aus:

   curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
   San Francisco International Airport
   

7. Die API hat jetzt ein Limit von fünf Anfragen pro Sekunde. Führen Sie den folgenden Befehl aus, um Traffic an die API zu senden und das Kontingentlimit auszulösen.

   ./generate_traffic_with_key.sh $API_KEY
   

8. Nachdem Sie das Skript fünf bis zehn Sekunden lang ausgeführt haben, geben Sie Control+C ein, um es anzuhalten.

9. Senden Sie eine weitere authentifizierte Anfrage an die API.

   ./query_api_with_key.sh $API_KEY
   

   Die Ausgabe sieht etwa so aus:

   {
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
     {
      "@type": "type.googleapis.com/google.rpc.DebugInfo",
      "stackEntries": [],
      "detail": "internal"
     }
    ]
   }
   

Wenn Sie eine andere Antwort erhalten, führen Sie das Skript generate_traffic_with_key.sh noch einmal aus und wiederholen dann den Vorgang.

Sie haben die Rate für Ihre API eingeschränkt. Sie können auch unterschiedliche Limits für verschiedene API-Methoden festlegen, mehrere Arten von Kontingenten erstellen und die API-Verwendung einzelner Nutzer erfassen.

Weitere Informationen finden Sie unter Über Kontingente.

Entwicklerportal für die API erstellen

Sie können mit dem Cloud Endpoints-Portal ein Entwicklerportal erstellen. Das ist eine Website zur Interaktion mit der Beispiel-API. Weitere Informationen finden Sie unter Übersicht über das Cloud Endpoints-Portal.

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen in Rechnung gestellt werden:

Zur Vermeidung von Gebühren können Sie Ihr Google Cloud-Projekt löschen und so die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beenden.

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:
• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, z. B. eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Nächste Schritte

• Endpoints im Überblick:

  • Über Endpoints
  • Architekturübersicht zu Endpoints

• Andere von Endpoints unterstützte API-Frameworks kennenlernen:

  • OpenAPI-Spezifikation
  • Endpoints für gRPC APIs
  • Endpoints Frameworks

• Beispiel-API mithilfe einer Anleitung für eines der API-Frameworks konfigurieren und bereitstellen:

  • Endpoints for OpenAPI: Anleitungen
  • Endpoints for gRPC: Anleitungen
  • Endpoints Frameworks: Anleitungen