Decorators

Die Python-Decorators für Cloud Endpoints Frameworks beschreiben die API-Konfiguration, Methoden, Parameter und weitere wichtige Details, die die Attribute und das Verhalten des Endpunkts definieren.

Auf dieser Seite werden die verfügbaren Decorators eingehend erläutert. Wie Sie die Decorators zum Erstellen Ihrer API verwenden, erfahren Sie unter:

API definieren (@endpoints.api)

Sie können für @endpoints.api mehrere Argumente angeben, um die API zu definieren. In der folgenden Tabelle werden die verfügbaren Argumente beschrieben:

@endpoints.api-Argumente Beschreibung Beispiel
allowed_client_ids Erforderlich, wenn Ihre API Authentifizierung nutzt. Liste der Client-IDs für Clients, die Tokens anfragen können. Weitere Informationen finden Sie unter Erlaubte Client-IDs und -Zielgruppen. allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID]
api_key_required Optional. Schränkt den Zugriff auf Anfragen mit einem API-Schlüssel ein. api_key_required=True
audiences Erforderlich, wenn die API eine Authentifizierung verwendet und Android-Clients unterstützt werden. Für Google ID-Tokens kann dies eine Liste mit Client-IDs sein, in deren Namen Tokens angefragt werden. Wenn die Tokens vom Authentifizierungsdienst eines Drittanbieters (z. B.: Auth0) ausgegeben werden, muss es sich um eine Wörterbuchzuordnung von den Namen der Authentifizierer zur Liste der Zielgruppe handeln. Weitere Informationen finden Sie unter Erlaubte Client-IDs und -Zielgruppen. audiences=['1-web-apps.apps.googleusercontent.com'] oder audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]}
base_path Optional Stellt Ihre API über den angegebenen Pfad bereit. Wenn Sie dieses Argument angeben, müssen Sie auch den Abschnitt handlers in der Datei app.yaml ändern. Siehe API über anderen Pfad bereitstellen.
canonical_name Optional. Legt in der Clientbibliothek einen anderen oder lesbareren Namen für die API fest. Dieser Name dient als Basis für die Namensgenerierung in der Clientbibliothek. Die Backend API verwendet weiterhin den mit dem Attribut name festgelegten Namen.

Beispiel: Wenn in der API das Attribut name auf dfaanalytics gesetzt wurde, können Sie mit diesem Attribut den kanonischen Namen DFA Group Analytics angeben. Die generierten Clientklassen enthalten in diesem Fall den Namen DfaGroupAnalytics.

Sie sollten die entsprechenden Leerzeichen zwischen den Namen einfügen. Diese werden durch die entsprechenden Binnenmajuskel oder Unterstriche ersetzt.		 canonical_name='DFA Analytics'
description Eine kurze Beschreibung der API. Diese wird im Discovery-Dienst bereitgestellt und kann optional für die Dokumentationsgenerierung verwendet werden, wie in Clientbibliotheken generieren beschrieben. description='Sample API for a simple game'
documentation Optional Die URL, unter der Nutzer eine Dokumentation zu dieser API-Version finden können. Sie wird in API Explorer unter "Weitere Informationen" am oberen Rand der API Explorer-Seite angezeigt. Nutzer erhalten darüber Informationen zu Ihrem Dienst. documentation='http://link_to/docs'
hostname Der Hostname Ihrer App Engine-Anwendung. Das Befehlszeilentool für Endpoints Frameworks verwendet den hier angegebenen Wert, wenn ein Discovery-Dokument oder ein OpenAPI-Dokument generiert wird. Wenn Sie hier keinen Hostnamen angeben, müssen Sie ihn in der Datei app.yaml im Feld application angeben. Alternativ können Sie beim Bereitstellen der App Engine-Anwendung Ihre Projekt-ID angeben. hostname='your_app_id.appspot.com'
issuers Optional Die benutzerdefinierte Konfiguration für den JWT-Aussteller. Dies sollte eine Wörterbuchzuordnung von Ausstellernamen zu Objekten vom Typ endpoints.Issuersein. issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")}
name Erforderlich Der Name der API, der als Präfix für alle Methoden und Pfade der API genutzt wird. Der Wert für name:
  • muss mit einem Kleinbuchstaben beginnen.
  • muss mit dem regulären Ausdruck [a-z]+[A-Za-z0-9] übereinstimmen. Der Rest des Namens kann aus Groß- und Kleinbuchstaben sowie Zahlen bestehen.
Um im Rahmen eines einzelnen Dienstes mehrere APIs bereitzustellen, müssen alle API-Namen mit dem regulären Ausdruck [a-z][a-z0-9]{0,39} übereinstimmen. Dies bedeutet, der Name muss mit einem Kleinbuchstaben beginnen, die restlichen Zeichen müssen Kleinbuchstaben oder Zahlen sein und der Name darf maximal 40 Zeichen lang sein.		 name='yourApi' oder name='yourapi'
limit_definitions Optional. Dient zum Definieren von Kontingenten für die API. Weitere Informationen finden Sie unter limit_definitions.
owner_domain Optional Der Domainname der Entität, die Inhaber der API ist. Wird beim Erstellen der Clientbibliothek für die API zusammen mit owner_name als Hinweis für einen passenden Namen angegeben. Der Paketpfad ist die Umkehrung von owner_domain und package_path, falls angegeben. Standardmäßig wird appid.apppost.com verwendet. owner_domain='your-company.com'
owner_name Optional Der Name der Entität, die Inhaber der API ist. Wird beim Erstellen der Clientbibliothek für die API zusammen mit owner_domain als Hinweis für einen passenden Namen angegeben. owner_name='Your-Company'
package_path Optional Wird verwendet, um den Bereich des "Pakets", zu dem diese API gehört, mit Werten festzulegen, die durch / getrennt werden und logische Gruppen von APIs angeben.

Beispielsweise führt der Wert cloud/platform dazu, dass für den Pfad der Clientbibliothek cloud/platform/<ApiName> und für das Paket der Clientbibliothek cloud.plaform.<ApiName>festgelegt wird.		 package_path='cloud/platform'
scopes Falls nicht anders angegeben, ist dies standardmäßig der E-Mail-Bereich https://www.googleapis.com/auth/userinfo.email, der für OAuth benötigt wird. Sie können diesen überschreiben, um mehr OAuth 2.0-Bereiche festzulegen. Wenn Sie die hier angegebenen Bereiche für eine bestimmte API-Methode überschreiben möchten, geben Sie im Decorator @endpoints.method andere Bereiche an. Wenn Sie jedoch mehr als einen Bereich definieren, beachten Sie, dass die Überprüfung des Bereichs bestanden wird, wenn das Token für einen beliebigen der angegebenen Bereiche erstellt wurde. Damit mehrere Bereiche Voraussetzung sind, geben Sie einen einzelnen String mit einem Leerzeichen zwischen den einzelnen Bereichen an. scopes=['ss0', 'ss1 and_ss2']
title Optional. Der im APIs Explorer angegebene Titel Ihrer API, der auch im Discovery- und Verzeichnisdienst bereitgestellt wird. title='My Backend API'
version Erforderlich. Gibt Ihre Version von Cloud Endpoints an. Dieser Wert wird im Pfad Ihrer API angezeigt. Wenn Sie einen mit dem SemVer-Standard kompatiblen Versionsstring angeben, wird beim Bereitstellen der API nur die Hauptversionsnummer im API-Pfad angezeigt. So hat beispielsweise eine API mit dem Namen echo und der Version 2.1.0 einen Pfad wie /echo/v2. Wenn Sie die echo API auf Version 2.2.0 aktualisieren und eine abwärtskompatible Änderung vornehmen, bleibt der Pfad /echo/v2 bestehen. Dadurch können Sie die API-Versionsnummer aktualisieren, wenn Sie eine abwärtskompatible Änderung vornehmen, ohne bestehende Pfade für Ihre Clients zu unterbrechen. Wenn Sie jedoch die echo API auf Version 3.0.0 aktualisieren, weil Sie eine nicht abwärtskompatible Änderung vornehmen, ändert sich der Pfad in /echo/v3. version='v1' oder version='2.1.0'

limit_definitions

Wenn Sie Kontingente für die API festlegen möchten, geben Sie das optionale Argument limit_definitions für @endpoints.api an. Um ein Kontingent zu konfigurieren, müssen Sie außerdem Folgendes tun:

  • Version 2.4.5 oder höher der Endpoints Frameworks-Bibliothek installieren
  • In Methoden-Decorator für jede Methode, auf die Sie ein Kontingent anwenden möchten, das Argument metric_costs einbinden

Weitere Informationen zu allen Schritten, die zum Einrichten eines Kontingents erforderlich sind, finden Sie unter Kontingente konfigurieren.

Geben Sie eine Liste mit einer oder mehreren Instanzen vom Typ LimitDefinition an. Beispiel:

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

Jede Instanz LimitDefinition muss folgenden Werte haben:

Element Beschreibung
name Der Name für den API-Anfragezähler. In der Regel ist dies der Anfragetyp (z. B. "Leseanfragen" oder "Schreibanfragen"), der das Kontingent eindeutig identifiziert.
Anzeigename

Der Text, der auf dem Tab Kontingente auf der Seite Endpoints > Dienste der GCP Console angezeigt wird, um das Kontingent zu bestimmen. Dieser Text wird den Nutzern Ihrer API auch auf der Seite Kontingente von "IAM & Verwaltung" und "APIs & Dienste" angezeigt. Der Anzeigename darf nicht länger als 40 Zeichen sein.

Zum besseren Verständnis wird der Text "pro Minute und Projekt" automatisch an den Anzeigenamen auf der Seite "Kontingente" angehängt. Um Einheitlichkeit mit den Anzeigenamen von Google-Diensten zu wahren, die auf der Seite "Kontingente" aufgeführt sind und von den Nutzern Ihrer API gesehen werden, empfehlen wir für den Anzeigenamen Folgendes:

  • Verwenden Sie "Anfragen", wenn Sie nur einen Messwert haben.
  • Wenn Sie mehrere Messwerte haben, sollte jeder den Typ der Anfrage beschreiben und das Wort "Anfragen" enthalten (zum Beispiel "Leseanfragen" oder "Schreibanfragen").
  • Verwenden Sie "Kontingenteinheiten" anstelle von "Anfragen", wenn die Kosten für dieses Kontingent größer als 1 sind.

Limit Ein ganzzahliger Wert, der die maximale Anzahl von Anfragen pro Minute pro Nutzerprojekt für das Kontingent angibt.

Beispiel

quota_limits = [
  endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),
  endpoints.LimitDefinition('list-requests', 'List Requests', 100),
  endpoints.LimitDefinition('write-requests', 'Write Requests', 50)
]

@endpoints.api(name='bookstore',
               version='v1',
               limit_definitions=quota_limits)

Erlaubte Client-IDs und -Zielgruppen

Für die OAuth2-Authentifizierung wird ein OAuth2-Token an eine spezielle Client-ID ausgegeben, was bedeutet, dass diese Client-ID zur Beschränkung des Zugriffs auf Ihre APIs verwendet werden kann. Wenn Sie Android-Apps in der Google Cloud Console registrieren, erstellen Sie eine Client-ID dafür. Diese Client-ID fordert von Google ein OAuth2-Token für die Authentifizierung an. Wenn die Backend API durch Authentifizierung geschützt ist, wird ein OAuth2-Zugriffstoken gesendet und von Endpoints Framework für App Engine geöffnet. Die Client-ID wird dann aus dem Token extrahiert und mit der Liste der vom Backend akzeptierten Client-IDs (allowed_client_ids) abgeglichen.

Die Liste allowed_client_ids sollte alle Client-IDs enthalten, die Sie über die Google Cloud Console für Ihre Web-, Android- und andere Clientanwendungen erhalten haben. Dies bedeutet, die Clients müssen bei der API-Erstellung bekannt sein. Wenn Sie eine leere Liste angeben, kann kein Client auf die API zugreifen.

Beachten Sie, dass Sie in jeder API-Methode, in der Sie die ordnungsgemäße Authentifizierung prüfen möchten, endpoints.get_current_user() aufrufen müssen. Weitere Informationen finden Sie unter Nutzer authentifizieren.

Wenn Sie das Argument allowed_client_ids verwenden und authentifizierte Aufrufe an Ihre API mit API Explorer testen möchten, müssen Sie dessen Client-ID in der Liste allowed_client_ids angeben. Dazu verwenden Sie die Konstante endpoints.API_EXPLORER_CLIENT_ID. Wenn allowed_client_ids nur endpoints.API_EXPLORER_CLIENT_ID enthält und Sie die API bereitstellen, ist diese weiterhin öffentlich sichtbar und kann über API Explorer öffentlich aufgerufen werden.

Informationen zu Zielgruppen

Die Liste allowed_client_ids schützt die Back-End API vor nicht autorisierten Clients. Die Clients müssen jedoch zusätzlich geschützt werden, damit ihr Authentifizierungstoken ausschließlich für die gewünschte Back-End API einsetzbar ist. Für Android-Clients kann zu diesem Zweck das Argument audiences verwendet werden. Geben Sie darin die Client-ID der Backend API an.

Beachten Sie, dass beim Erstellen eines Google Cloud Console-Projekts automatisch eine Standard-Client-ID zur Nutzung durch das Projekt erstellt und benannt wird. Wenn Sie Ihre Back-End API in App Engine hochladen, wird diese Client-ID verwendet. Dies ist die unter Nutzer authentifizieren erwähnte Web-Client-ID.

Authentifizierungstokens von Dritten

Wenn Ihre Anwendung Authentifizierungstokens akzeptiert, bei denen es sich nicht um Google-ID-Token handelt und die von Drittanbietern ausgegeben werden, müssen Sie die Argumente audiences und issuers in @endpoints.api festlegen, um die Informationen zu den Drittanbietern bereitzustellen. Beispiel:

@endpoints.api(
        audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
        issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
                                           'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):

API-Methode (@endpoints.method) festlegen

Sie können die Einstellungen audiences, scopes und allowed_client_ids für die gesamte API mit @endpoints.api vornehmen. Für eine Methode kann dies mit @endpoints.method erfolgen. Wenn diese Einstellungen sowohl auf der API-Ebene als auch auf der Methodenebene festgelegt sind, wird die Methodeneinstellung vorrangig verwendet.

Um eine Methode in Ihrer API zu erstellen, dekorieren Sie die entsprechende Python-Methode mit @endpoints.method und geben Argumente zum Konfigurieren der Methodenverwendung an. Geben Sie beispielsweise an, welche Message-Klassen für Anfrage und Antwort verwendet werden sollen.

Die verfügbaren Argumente sind in der folgenden Tabelle aufgelistet

Argumente vom Typ @endpoints.method Beschreibung Beispiel
allowed_client_ids Diese Einstellung überschreibt das äquivalente Attribut, das in @endpoints.api angegeben ist. Weitere Informationen finden Sie unter Erlaubte Client-IDs und -Zielgruppen. ['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com']
api_key_required Optional. Schränkt den Zugriff auf Anfragen mit einem API-Schlüssel ein. api_key_required=True
audiences Überschreibt das äquivalente Argument, das in @endpoints.api angegeben ist. Weitere Informationen finden Sie unter Erlaubte Client-IDs und -Zielgruppen. ['1-web-apps.apps.googleusercontent.com']
metric_costs Optional. Gibt an, dass die Methode ein Kontingentlimit aufweist. Dies ist ein Wörterbuch mit folgenden Schlüssel/Wert-Paaren:
  • Name: Ein Name, den Sie im Argument limit_definitions für den API-Decorator angegeben haben.
  • Kosten: Eine Ganzzahl, die die Kosten für die einzelnen Anfragen angibt. Durch Angabe der Kosten können Methoden dasselbe Kontingent mit unterschiedlichen Raten nutzen. Wenn beispielsweise ein Kontingent ein Limit von 1.000 und Kosten von 1 hat, kann die aufrufende Anwendung 1.000 Anfragen pro Minute senden, bevor das Limit überschritten wird. Bei Kosten von 2 für dasselbe Kontingent kann eine aufrufende Anwendung nur 500 Anfragen pro Minute senden, bevor sie das Limit überschreitet.
 metric_costs={'read-requests': 1}
http_method Die zu verwendende HTTP-Methode. Wenn Sie diese nicht festlegen, wird standardmäßig 'POST' verwendet. 'GET'
name Ein alternativer Name für diese Methode. Der Wert für name:
  • muss mit Kleinbuchstaben beginnen.
  • muss mit dem regulären Ausdruck [a-z]+[A-Za-z0-9]* übereinstimmen.
 'yourApi'
path Der URI-Pfad für den Zugriff auf diese Methode. Wenn Sie ihn nicht festlegen, wird der Name der Python-Methode verwendet. Wenn Sie API-Verwaltung einbauen möchten, setzen Sie keinen Schrägstrich ans Pfadende. 'yourapi/path'
Klasse Request Message Die im Methodenaufruf verwendete Google Protocol RPC-Klasse Request Message. Alternativ können Sie den Namen der Klasse angeben. YourRequestClass
Klasse Response Message Die im Methodenaufruf verwendete Google Protocol RPC-Klasse Response Message. Alternativ können Sie den Namen der Klasse angeben. YourResponseClass

ResourceContainer für Pfad- oder Abfragestringargumente verwenden

Wenn die Anfrage Argumente für den Pfad oder Abfragestring enthält, können Sie nicht die einfache Klasse Message verwenden, wie unter API erstellen beschrieben. Stattdessen müssen Sie die Klasse ResourceContainer verwenden. Gehen Sie dabei so vor:

  1. Definieren Sie eine Message-Klasse, die alle Argumente hat, die im Anfragetext angegeben sind. Wenn der Anfragetext keine Argumente enthält, müssen Sie keine Message-Klasse definieren. Sie verwenden einfach message_types.VoidMessage. Beispiel:

    class Greeting(messages.Message):
    """Greeting that stores a message."""

    message = messages.StringField(1)

  2. Definieren Sie einen ResourceContainer mit der Klasse Message, die Sie im vorherigen Schritt als ersten Parameter definiert haben. Geben Sie die Pfad- und Abfragestringargumente in den nachfolgenden Parametern an. Beispiel:

    MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),

    Dabei ist das erste Argument die Klasse Messagefür die Daten im Anfragetext und times ist eine Zahl, die im Pfad oder Abfragestring der Anfrage erwartet wird.

  3. Stellen Sie den ResourceContainer der Methode zur Verfügung, die die Anfrage verarbeitet. Im ersten Parameter wird dabei die Klasse Message der Anfrage ersetzt, die andernfalls hier angegeben wäre. Dieses Snippet zeigt sowohl den ResourceContainer als auch die endpoints.method:

    # This ResourceContainer is similar to the one used for get_greeting, but
# this one also contains a request body in the form of a Greeting message.
MULTIPLY_RESOURCE = endpoints.ResourceContainer(
    Greeting,
    times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),
)

@endpoints.method(
    # This method accepts a request body containing a Greeting message
    # and a URL parameter specifying how many times to multiply the
    # message.
    MULTIPLY_RESOURCE,
    # This method returns a Greeting message.
    Greeting,
    path="greetings/multiply/{times}",
    http_method="POST",
    name="greetings.multiply",
)
def multiply_greeting(self, request):
    return Greeting(message=request.message * request.times)

  4. Binden Sie den Parameter path wie unten beschrieben ein, um Ihre API einzubeziehen:

  5. Wenn der ResourceContainer ein erforderliches Argument enthält, muss dieses in einer Clientanfrage entweder in einem Abfragestring (z. B. yourApi?times=2) oder im URL-Pfad (z. B. yourApi/2) enthalten sein. Damit die API jedoch den Wert des Arguments über den URL-Pfad erhalten kann, müssen Sie im API-Pfad auch den Namen des Arguments angeben. Sie sehen dies im Beispiel mit dem Argument {times} in path='yourApi/{times}.

Nächste Schritte