Cloud Endpoints-Kurzanleitung

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 Protokolle der Operations-Suite von Google Cloud 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. In den Anleitungen zu den jeweiligen API-Frameworks wird an einem Beispiel gezeigt, wie Sie eine API konfigurieren und bereitstellen:

Vorbereitung

  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, registrieren Sie sich hier für ein neues Konto.

  2. Wählen Sie in der Cloud Console auf der Projektauswahlseite ein Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

Cloud Shell starten

  1. Sehen Sie in der Cloud Console nach, ob Sie sich in dem Projekt befinden, das Sie für die Beispiel-API verwenden möchten.

  2. Öffnen Sie Cloud Shell.

    Cloud Shell öffnen

    Im unteren Bereich der 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.

    Cloud Shell-Sitzung

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

    gcloud components update
    

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 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
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

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
gcloud services enable endpoints.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-Back-End 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!

API-Aktivität verfolgen

Mit APIs, die mit Endpoints bereitgestellt werden, können Sie kritische Betriebsmesswerte in der 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
    
  2. Sehen Sie sich in der Cloud Console die Aktivitätsgrafiken für Ihre API an.

    Zur Seite "Endpoints-Dienste"

    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 Loganzeige werden die Anfragelogs für die API angezeigt.

  4. Öffnen Sie Cloud Shell.

    Cloud Shell öffnen

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

Kontingent zur API hinzufügen

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. Rufen Sie in der Cloud Console die Seite Anmeldedaten auf.

    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 Kopierenfile_copy.

  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 Ctrl-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

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Kurzanleitung verwendeten Ressourcen in Rechnung gestellt werden:

Um Gebühren zu vermeiden, können Sie Ihr Cloud-Projekt löschen und so die Abrechnung für alle in diesem Projekt verwendeten Ressourcen beenden.

  1. Wechseln Sie in der Cloud Console zur Seite Ressourcen verwalten.

    Zur Seite "Ressourcen verwalten"

  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen .
  3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.

Nächste Schritte