Erste Schritte mit Cloud Endpoints in der flexiblen App Engine-Umgebung (.NET) mit ESP

In dieser Anleitung wird erklärt, wie Sie eine .NET Core-Beispiel-API und den Extensible Service Proxy (ESP) konfigurieren und bereitstellen, der auf einer Instanz in der flexiblen App Engine-Umgebung ausgeführt wird. Die Beispiel-API wird in der OpenAPI-Spezifikation beschrieben. Sie erfahren in dieser Anleitung auch, wie Sie einen API-Schlüssel erstellen und in Anfragen an die API verwenden.

Eine Übersicht über Cloud Endpoints finden Sie in den Abschnitten Über Cloud Endpoints und Architekturübersicht zu Cloud Endpoints.

Ziele

Orientieren Sie sich beim Durcharbeiten der Anleitung an der folgenden Aufgabenliste. Alle Aufgaben sind erforderlich, um Anfragen sicher an die API senden zu können.

  1. Richten Sie ein Google Cloud Projekt ein, installieren Sie die erforderliche Software und erstellen Sie eine App Engine-Anwendung. Siehe Vorbereitung.
  2. Beispielcode herunterladen: Siehe Beispielcode abrufen.
  3. Konfigurieren Sie die Datei openapi.yaml, mit der Endpoints konfiguriert wird. Siehe Endpoints konfigurieren.
  4. Die Endpoints-Konfiguration bereitstellen, um einen Endpoints-Dienst zu erstellen. Siehe Endpoints-Konfiguration bereitstellen.
  5. Die Beispiel-API und den ESP in App Engine bereitstellen. Siehe API-Backend bereitstellen.
  6. Eine Anfrage an die API senden. Siehe Anfrage an die API senden.
  7. API-Aktivitäten verfolgen. Siehe API-Aktivitäten verfolgen.
  8. So vermeiden Sie Gebühren für Ihr Google Cloud -Konto. Siehe Bereinigen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.

Hinweis

Hinweis

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Notieren Sie sich die Projekt-ID, da sie später benötigt wird.
  4. Für diese Anleitung ist das .NET Core 2.x SDK erforderlich, das Sie mit einem beliebigen Texteditor verwenden können. Es ist nicht erforderlich, eine integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) zu verwenden. Dennoch empfehlen wir der Einfachheit halber, eine der folgenden IDEs zu nutzen:

  5. Sie benötigen eine Anwendung, um Anfragen an die Beispiel-API zu senden. Diese Anleitung enthält ein Beispiel, bei dem Invoke-WebRequest verwendet wird. Der Befehl wird in PowerShell ab Version 3.0 unterstützt.

  6. Laden Sie die Google Cloud CLI herunter.
  7. Aktualisieren Sie die gcloud CLI und installieren Sie die Endpoints-Komponenten. 
    gcloud components update
  8. Die Google Cloud CLI (gcloud) muss berechtigt sein, auf Ihre Daten und Dienste auf Google Cloudzuzugreifen: 
    gcloud auth login
     Ein neuer Browsertab wird geöffnet. Wählen Sie dort ein Konto aus.
  9. Legen Sie für das Standardprojekt Ihre Projekt-ID fest: 
    gcloud config set project YOUR_PROJECT_ID

    Ersetzen Sie dabei YOUR_PROJECT_ID durch die ID Ihres Projekts in Google Cloud . Wenn Sie weitere Google Cloud -Projekte mit gcloud verwalten möchten, lesen Sie gcloud CLI-Konfigurationen verwalten.

  10. Wählen Sie die Region aus, in der Sie die App Engine-Anwendung erstellen möchten. Führen Sie den folgenden Befehl aus, um eine Liste der Regionen abzurufen: 
    gcloud app regions list
  11. Erstellen Sie eine App Engine-Anwendung. Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID und YOUR_REGION durch die Region, in der die App Engine-Anwendung erstellt werden soll. 
      gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION

Beispielcode abrufen

So laden Sie die Beispiel-API herunter:

  1. Laden Sie den Beispielcode als ZIP-Datei herunter.

  2. Extrahieren Sie die ZIP-Datei und wechseln Sie zum Verzeichnis dotnet-docs-samples-master\endpoints\getting-started.

  3. Öffnen Sie GettingStarted.sln mit Visual Studio oder verwenden Sie einen Editor Ihrer Wahl, um die Dateien im Verzeichnis endpoints\getting-started\src\IO.Swagger zu bearbeiten.

Endpoints konfigurieren

Sie benötigen ein OpenAPI-Dokument auf Grundlage von OpenAPI 2.0 oder OpenAPI 3.x, das die Oberfläche Ihrer Apps sowie Authentifizierungsanforderungen beschreibt. Weitere Informationen finden Sie unter Unterstützte OpenAPI-Versionen.

Außerdem müssen Sie ein Google-spezifisches Feld hinzufügen, das die URL für jede App enthält, damit ESPv2 die zum Aufrufen einer App erforderlichen Informationen zur Verfügung stehen. Falls Sie mit OpenAPI noch nicht vertraut sind, stehen unter OpenAPI – Übersicht weitere Informationen bereit.

OpenAPI 2.0

Wenn Sie Endpoints mit einer OpenAPI 2.0-Spezifikation konfigurieren möchten, können Sie die Datei openapi-appengine.yaml verwenden, die im Verzeichnis dotnet-docs-samples-master\endpoints\getting-started des heruntergeladenen Beispielcodes verfügbar ist.

Der Inhalt der OpenAPI 2.0-Spezifikation sollte in etwa so aussehen:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR_PROJECT_ID.appspot.com"
consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_jwt:
          audiences:
          # This must match the "aud" field in the JWT. You can add multiple
          # audiences to accept JWTs from multiple clients.
          - "echo.endpoints.sample.google.com"
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_id_token:
          audiences:
          # Your OAuth2 client's Client ID must be added here. You can add
          # multiple client IDs to accept tokens from multiple clients.
          - "YOUR-CLIENT-ID"

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR-SERVICE-ACCOUNT-EMAIL"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"

Ersetzen Sie in der Zeile mit dem Feld „host“ den Eintrag YOUR_PROJECT_ID durch Ihre Google Cloud Projekt-ID.

OpenAPI 3.x

Wenn Sie Endpoints mit einer OpenAPI 3.x-Spezifikation konfigurieren möchten, können Sie den Inhalt der Datei openapi-appengine.yaml im Verzeichnis dotnet-docs-samples-master\endpoints\getting-started des heruntergeladenen Beispielcodes ersetzen:

  1. Öffnen Sie die Datei openapi-appengine.yaml in einem Texteditor und ersetzen Sie den Inhalt durch Folgendes: 
    openapi: 3.0.4
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
servers:
  - url: "https://YOUR_PROJECT_ID.appspot.com"
    x-google-endpoint: {}
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      requestBody:
        description: "Message to echo"
        required: true
        content: