Annotationen für Endpoints Frameworks beschreiben die API-Konfiguration, Methoden, Parameter und weitere wichtige Details, die die Attribute und das Verhalten des Endpunkts definieren.
Weitere Informationen zum Einfügen von Anmerkungen mithilfe eines Maven-Projekts finden Sie unter Code schreiben und annotieren. Maven App Engine Cloud Endpoints-Artefakte werden zur Verfügung gestellt, um eine Backend API zu erstellen und daraus eine Clientbibliothek zu generieren.
Die Annotation @Api
legt die Konfiguration und das Verhalten der gesamten API fest. Sie wirkt sich auf alle in der API bereitgestellten Klassen und damit verbundenen Methoden aus.
Alle öffentlichen, nicht-statischen, brückenlosen Methoden einer mit @Api
annotierten Klasse werden in der öffentlichen API bereitgestellt.
Wenn Sie für eine bestimmte Methode eine spezielle API-Konfiguration benötigen,
kann optional
@ApiMethod
um die Konfiguration für einzelne Methoden festzulegen.
Zum Konfigurieren dieser Annotationen legen Sie verschiedene Attribute fest, wie in den folgenden Tabellen gezeigt.
@Api
: API-bezogene Annotationen
Die Anmerkung
@Api
Konfiguriert die gesamte API und gilt für alle öffentlichen Methoden einer Klasse
sofern sie nicht durch @ApiMethod
überschrieben wird.
Zum Überschreiben einer bestimmten @Api
-Annotation für eine bestimmte Klasse in
einer API finden Sie unter
@ApiClass
und
@ApiReference
Erforderliche Importe
Für dieses Feature ist folgender Import erforderlich:
import com.google.api.server.spi.config.Api;
Attribute
@Api-Attribute | Beschreibung | Beispiel |
---|---|---|
audiences |
Erforderlich, wenn die API eine Authentifizierung verwendet und Android-Clients unterstützt werden. Weitere Informationen finden Sie unter Client-IDs und Zielgruppen. | audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"} |
apiKeyRequired |
Optional. Schränkt den Zugriff auf Anfragen mit einem API-Schlüssel ein. | apiKeyRequired = AnnotationBoolean.TRUE |
authenticators |
Erforderlich, wenn sich die API mithilfe von Firebase, Auth0 oder Dienstkonten authentifiziert. Dieses Attribut ist nicht erforderlich, wenn die API-Authentifizierung mithilfe von Google ID-Tokens erfolgt. Sie können dies auf der API-Ebene oder für jede Methode individuell festlegen. Legen Sie {EspAuthenticator.class} fest oder schreiben Sie Ihre eigene benutzerdefinierte Authentifizierung wie unter Schnittstelle "Authenticator" beschrieben. |
authenticators = {EspAuthenticator.class} |
backendRoot |
Verworfen. Ändern Sie url-pattern in Ihrer Datei web.xml im Abschnitt EndpointsServlet , um Ihre API über einen anderen Pfad bereitzustellen. |
<url-pattern>/example-api/*</url-pattern> |
canonicalName |
Legt in der Clientbibliothek einen anderen oder lesbareren Namen für die API fest. Dieser Name wird zum Generieren von Namen in der Clientbibliothek verwendet. Die Back-End-API nutzt weiterhin den in der Eigenschaft name festgelegten Wert.Wenn in der API name auf dfaanalytics festgelegt ist, 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 Camel Case oder Unterstriche ersetzt. |
canonicalName = "DFA Analytics:" n |
clientIds |
Erforderlich, wenn Ihre API Authentifizierung nutzt. Liste der Client-IDs für Clients, die Tokens anfragen können. Weitere Informationen finden Sie unter Client-IDs und Zielgruppen. | clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"} |
defaultVersion |
Gibt an, ob eine Standardversion verwendet wird, wenn im Attribut version keine Version angegeben ist. |
defaultVersion = AnnotationBoolean.TRUE |
description |
Eine kurze Beschreibung der API. Diese wird im Discovery-Dienst bereitgestellt und kann optional für die Dokumentationsgenerierung verwendet werden. | description = "Sample API for a simple game" |
documentationLink |
Die URL, unter der Nutzer Dokumentation zu dieser Version der API finden können. Sie wird im API Explorer unter "Weitere Informationen" am oberen Rand der API Explorer-Seite angezeigt, damit Nutzer Informationen zu Ihrem Dienst erhalten können. | documentationLink = "http://link_to/docs" |
issuers |
Die benutzerdefinierte Konfiguration für den JWT-Aussteller. | issuers = { @ApiIssuer(name = "auth0", issuer = "https://test.auth0.com/authorize", jwksUri = "https://test.auth0.com/.well-known/jwks.json") } |
issuerAudiences |
Zielgruppen für individuelle Aussteller. | issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) } |
limitDefinitions |
Optional. Definiert Kontingente für Ihre API. Weitere Informationen finden Sie unter @ApiLimitMetric . |
limitDefinitions = { @ApiLimitMetric(name = "read-requests", displayName = "Read requests", limit = 1000)} |
name |
Der Name der API, der als Präfix für alle Methoden und Pfade der API genutzt wird. Für den Wert name gelten folgende Bedingungen:
name nicht festlegen, wird die Standardeinstellung myapi verwendet. |
name = "foosBall" |
namespace |
Konfiguriert den Namespace für generierte Clients. Weitere Informationen finden Sie unter @ApiNamespace . |
namespace=@ApiNamespace(ownerDomain="your-company.com", ownerName="YourCo", packagePath="cloud/platform" ) |
root |
Verworfen. Ändern Sie url-pattern in Ihrer Datei web.xml im Abschnitt EndpointsServlet , um Ihre API über einen anderen Pfad bereitzustellen. |
<url-pattern>/example-api/*</url-pattern> |
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 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. Legen Sie mehrere Bereiche vorzugsweise in einem einzigen String mit Leerzeichen zwischen den Bereichen fest. Wenn Sie die hier angegebenen Bereiche für eine bestimmte API-Methode überschreiben möchten, geben Sie in der Annotation @ApiMethod andere Bereiche an. |
scopes = {"ss0", "ss1 and_ss2"} |
title |
Der im API Explorer angegebene Titel Ihrer API, der auch im Discovery- und Verzeichnisdienst bereitgestellt wird. | title = "My Backend API" |
transformers |
Gibt eine Liste benutzerdefinierter Transformer an. Empfohlen wird jedoch die alternative Annotation @ApiTransformer . Das Attribut wird durch @ApiTransformer überschrieben. |
transformers = {BazTransformer.class} |
version |
Gibt Ihre Version des Endpunkts an. Ohne Angabe wird die Standardeinstellung v1 verwendet. |
version = "v2" |
Beispiel für eine @Api
-Annotation
Diese Annotation wird vor der Klassendefinition platziert:
Client-IDs und Zielgruppen
Für die OAuth2-Authentifizierung wird ein OAuth2-Token an eine spezielle Client-ID ausgegeben, was bedeutet, dass Sie die Client-ID zur Beschränkung des Zugriffs auf Ihre APIs verwenden können.
Wenn Sie eine Android-App 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 geöffnet. Die Client-ID wird dann aus dem Token extrahiert und mit der Liste der vom Backend akzeptierten Client-IDs (Liste clientIds
) abgeglichen.
Wenn Sie möchten, dass die Endpoints API Anrufer authentifiziert, müssen Sie eine Liste der clientIds
angeben, die Tokens anfordern dürfen. Die Liste sollte alle Client-IDs enthalten, die Sie über die Google Cloud Console für Ihre Web- oder Android-Clients erhalten haben. Dies bedeutet, die Clients müssen bei der API-Erstellung bekannt sein. Wenn Sie mit {}
eine leere Liste angeben, können Clients keine der durch Authentifizierung geschützten Methoden aufrufen.
Wenn Sie das Attribut clientIds
verwenden und authentifizierte Aufrufe an Ihre API mit Google API Explorer testen möchten, müssen Sie dessen Client-ID in der Liste der clientIds
angeben. Verwenden Sie dazu den Wert com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID
.
Informationen zu Zielgruppen
Die Liste clientIds
schützt die Back-End API vor nicht autorisierten Clients. Aber
Es ist zusätzlicher Schutz erforderlich, um die Clients zu schützen, damit ihr Authentifizierungstoken
funktioniert nur für die
gewünschte Back-End-API. Für Android-Clients kann zu diesem Zweck das Attribut audiences
verwendet werden. Geben Sie darin die Client-ID der Backend API an.
Wenn Sie ein Google Cloud Console-Projekt erstellen, Die ID wird automatisch erstellt und zur Verwendung durch das Projekt benannt. Wenn Sie Ihre Back-End API in App Engine hochladen, wird diese Client-ID verwendet. Dies ist die unter API-Authentifizierung erwähnte Web-Client-ID.
@ApiMethod
: Method-scoped annotations
Die Anmerkung
@ApiMethod
wird verwendet, um eine andere API-Konfiguration als die Standardeinstellungen des
@Api
- oder @ApiClass
-Anmerkungen. Dies ist optional: Alle öffentlichen, nicht-statischen, brückenlosen Methoden einer mit @Api
annotierten Klasse werden mit oder ohne @ApiMethod
-Annotation in der API bereitgestellt.
Mithilfe von Attributen können Sie in dieser Annotation Details einer einzelnen API-Methode konfigurieren. Wenn in @Api
und @ApiMethod
Werte für dasselbe Attribut festgelegt sind, hat @ApiMethod
Priorität.
Erforderliche Importe
Für dieses Feature sind folgende Importe erforderlich:
import com.google.api.server.spi.config.AnnotationBoolean;
import com.google.api.server.spi.config.ApiMethod;
import com.google.api.server.spi.config.ApiMethod.HttpMethod;
Attribute
@ApiMethod-Attribute | Beschreibung | Beispiel |
---|---|---|
apiKeyRequired |
Optional. Schränkt den Zugriff auf Anfragen mit einem API-Schlüssel ein. | apiKeyRequired = AnnotationBoolean.TRUE |
audiences |
Anzugeben, wenn die Konfiguration in @API überschrieben werden soll. Weitere Informationen finden Sie unter Client-IDs und Zielgruppen. |
audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"} |
authenticators |
Erforderlich, wenn sich die API mithilfe von Firebase, Auth0 oder Dienstkonten authentifiziert und Sie das Attribut nicht auf der API-Ebene festgelegt haben. Dieses Attribut ist nicht erforderlich, wenn die API-Authentifizierung mithilfe von Google ID-Tokens erfolgt. Legen Sie {EspAuthenticator.class} fest oder schreiben Sie Ihre eigene benutzerdefinierte Authentifizierung wie unter Schnittstelle "Authenticator" beschrieben. |
authenticators = {EspAuthenticator.class} |
clientIds |
Liste der Client-IDs für Clients, die Tokens anfragen können. Erforderlich, wenn die API eine Authentifizierung verwendet. | clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"} |
httpMethod |
Die zu verwendende HTTP-Methode. Wenn Sie diese Einstellung nicht festlegen, wird anhand des Namens der Methode eine Standardeinstellung ausgewählt. | httpMethod = HttpMethod.GET |
issuerAudiences |
Anzugeben, wenn die Konfiguration in @Api überschrieben werden soll. |
issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) } |
metricCosts |
Optional. Gibt an, dass die Methode ein Kontingentlimit aufweist. Weisen Sie die Annotation @ApiMetricCost dem Wert metricCosts zu. Außerdem müssen Sie das Attribut limitDefinitions angeben, um das Kontingent in der Annotation @Api zu definieren. Die Annotation @ApiMetricCost verwendet die folgenden Attribute:
|
metricCosts = { @ApiMetricCost(name = read-requests", cost = 1) } |
name |
Der in der generierten Clientbibliothek angegebene Name der Methode. Diesem wird automatisch der API-Name vorangestellt, um die Methode eindeutig zu benennen. Für den Wert name gelten folgende Bedingungen:
name nicht festlegen, wird die Standardeinstellung myapi verwendet. |
name = "foosBall.list" |
path |
Der URI-Pfad, der zum Zugriff auf die Methode verwendet wird. Wenn Sie diese Einstellung nicht festlegen, wird ein Standardpfad anhand des Namen der Java-Methode verwendet. Wenn Sie API-Verwaltung einbauen möchten, setzen Sie keinen Schrägstrich ans Pfadende. | path = "foos" |
scopes |
Geben Sie mindestens einen OAuth 2.0-Bereich an, um diese Methode aufrufen zu können. Wenn Sie für eine Methode scopes festlegen, wird die Einstellung in der Annotation @Api überschrieben. Wenn Sie 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"} |
Beispiel für eine @ApiMethod
-Annotation
Diese Annotation wird vor der Methodendefinition innerhalb einer Klasse platziert:
Methoden mit einer Entität als Parameter sollten für Einfügungen HttpMethod.POST
und für Aktualisierungen HttpMethod.PUT
verwenden:
@Named
Die Annotation @Named
ist für alle Parameter ohne Entität erforderlich, die an serverseitige Methoden übergeben werden. Diese Annotation gibt den Namen des Parameters in der hier injizierten Anfrage an. Ein nicht mit @Named
annotierter Parameter wird mit dem gesamten Anfrageobjekt injiziert.
Erforderliche Importe
Für dieses Feature sind folgende Importe erforderlich:
import javax.inject.Named;
Hier ein Anwendungsbeispiel für @Named
:
Dabei gibt @Named
an, dass nur der Parameter id
in die Anfrage injiziert wird.
@ApiLimitMetric
In diesem Abschnitt werden die Annotationen beschrieben, die zum Definieren Kontingente für Ihre API. Weitere Informationen finden Sie unter Kontingente konfigurieren finden Sie alle Schritte, die zum Einrichten eines Kontingents erforderlich sind.
Sie weisen die Annotation @ApiLimitMetric
dem Attribut limitDefinitions
der API-bezogenen Annotationen zu.
Sie müssen @ApiMetricCost
auch hinzufügen zu:
@ApiMethod
Anmerkungen
für jede Methode, auf die Sie ein Kontingent anwenden möchten.
Erforderliche Importe
Für dieses Feature ist folgender Import erforderlich:
import com.google.api.server.spi.config.ApiLimitMetric;
Attribute
@ApiLimitMetric -Attribute
|
Beschreibung |
---|---|
Name | Der Name für das Kontingent. In der Regel ist dies der Anfragetyp (z. B. "Leseanfragen" oder "Schreibanfragen"), der das Kontingent zweifelsfrei identifiziert. |
displayName | Der Text, der auf dem Tab Kontingente auf der Seite Endpoints > Dienste der Google Cloud Console angezeigt wird, um das Kontingent zu identifizieren. Dieser Text wird auch den Nutzern Ihrer API 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:
|
Limit | Ein ganzzahliger Wert, der die maximale Anzahl von Anfragen pro Minute pro Nutzerprojekt für das Kontingent angibt. |
Beispiel
limitDefinitions = {
@ApiLimitMetric(
name = "read-requests",
displayName = "Read requests",
limit = 1000),
@ApiLimitMetric(
name = "write-requests",
displayName = "Write requests",
limit = 50),
}
@ApiNamespace
Durch die Annotation @ApiNamespace
wird anstelle des während der Generierung der Clientbibliotheken angelegten Standard-Namespaces der von Ihnen angegebene Namespace verwendet.
Wenn Sie diese Annotation nicht verwenden, wird als Namespace standardmäßig die umgekehrte Form von your-project-id.appspot.com
verwendet. Der Paketpfad lautet somit com.appspot.your-project-id.yourApi
.
Sie können den Standard-Namespace ändern. Geben Sie dazu innerhalb der Annotation @Api
die Annotation @ApiNamespace
an:
Setzen Sie das ownerDomain
-Attribut auf Ihre eigene Unternehmensdomain und ownerName
auf Ihren Firmennamen, z. B. your-company.com
. Für den Paketpfad wird die Umkehrung von ownerDomain
verwendet: com.your-company.yourApi
.
Mit dem Attribut packagePath
können Sie optional weitere Bereiche angeben.
Wenn Sie beispielsweise packagePath
auf cloud
setzen, wird als Paketpfad in der Clientbibliothek com.your-company.cloud.yourApi
verwendet. Durch Angabe des Trennzeichens /
: packagePath="cloud/platform"
können Sie dem Paketpfad weitere Werte hinzufügen.
@Nullable
Diese Annotation gibt an, dass ein Parameter einer Methode optional – und somit ein Abfrageparameter – ist. @Nullable
ist nur mit dem Parameter @Named
zulässig.
@ApiClass
In einer API mit mehreren Klassen können Sie mit @ApiClass
verschiedene Attribute für eine bestimmte Klasse angeben und entsprechende Attribute in der @Api
-Konfiguration überschreiben. Weitere Informationen finden Sie unter
@ApiClass
für abweichende Attribute in Klassen verwenden
finden Sie eine vollständige Beschreibung dieser Anmerkung.
@ApiReference
In einer API mit mehreren Klassen können Sie mit @ApiReference
eine alternative Methode der Annotationsübernahme angeben. Eine ausführliche Beschreibung dieser Annotation finden Sie unter @ApiReference
-Übernahme verwenden.
@ApiResourceProperty
@ApiResourceProperty
steuert, wie Ressourcenattribute in der API bereitgestellt werden.
In einem Attribut-Getter oder -Setter ist dadurch die Angabe eines Attributs für eine API-Ressource überflüssig. Wenn es sich um ein privates Feld handelt, können Sie die Annotation auch für das Feld selbst verwenden, um es in der API bereitzustellen. Auch den Namen eines Attributs in einer API-Ressource können Sie mit der Annotation ändern.
Erforderliche Importe
Für dieses Feature sind folgende Importe erforderlich:
import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;
Attribute
@ApiResourceProperty-Attribute | Beschreibung | Beispiel |
---|---|---|
ignored |
Mit der Einstellung AnnotationBoolean.TRUE wird das Attribut weggelassen. Wenn sie nicht angegeben oder auf AnnotationBoolean.FALSE gesetzt ist, wird das Attribut verwendet. |
@ApiResourceProperty(ignored = AnnotationBoolean.TRUE) |
name |
Legt den in der API bereitzustellenden Attributnamen fest, sofern angegeben. | @ApiResourceProperty(name = "baz") |
Beispielklasse mit @ApiResourceProperty
Das folgende Snippet zeigt eine Klasse, deren Attribut-Getter mit @ApiResourceProperty
annotiert wurden:
Im vorigen Code-Snippet wird @ApiResourceProperty
auf den Getter getBin
für das Attribut bin
angewendet. Die Attributeinstellung ignored
weist Endpoints Frameworks an, dieses Attribut in der API-Ressource wegzulassen.
@ApiResourceProperty
wird auch auf das private Feld visible
angewendet, das keinen Getter oder Setter hat. Durch die Verwendung dieser Annotation wird das Feld als Attribut in der API-Ressource verfügbar gemacht.
@ApiResourceProperty
wird im selben Snippet auch auf den Getter getFoobar
angewendet, der einen Attributwert für foobar
zurückgibt. name
in dieser Annotation veranlasst Endpoints Frameworks, den Attributnamen in der API-Ressource zu ändern. Der Attributwert selber bleibt unverändert.
Im obigen Beispiel-Snippet sieht die JSON-Darstellung eines Resp
-Objekts so aus:
{"baz": "foobar", "visible": "nothidden"}
@ApiTransformer
Die Annotation @ApiTransformer
legt fest, wie ein Typ in Endpoints durch Transformation zu und von einem anderen Typ bereitgestellt wird. (Der angegebene Transformer muss eine Implementierung von com.google.api.server.spi.config.Transformer
sein.)
Transformer werden vorzugsweise mit der Annotation @ApiTransformer
für eine Klasse angegeben. Sie können den benutzerdefinierten Transformer aber auch im Attribut transformer
der Annotation @Api
angeben.
Erforderliche Importe
Für dieses Feature ist folgender Import erforderlich:
import com.google.api.server.spi.config.ApiTransformer;
Beispielklasse mit @ApiTransformer
Das folgende Snippet zeigt eine mit @ApiTransformer
annotierte Klasse:
Diese Klasse wird von der Klasse BarTransformer
umgewandelt.
Beispiel für Endpoints-Transformer-Klasse
Das folgende Snippet zeigt ein Beispiel einer Transformer-Klasse mit dem Namen BarTransformer
.
Dies ist der im vorangegangenen Snippet @ApiTransformer
referenzierte Transformer:
Wenn ein Objekt mit dem Attribut bar
des Typs Bar
ohne den obigen Transformer vorliegt, wird das Objekt so dargestellt:
{"bar": {"x": 1, "y": 2}}
Mit dem Transformer wird das Objekt so dargestellt:
{"bar": "1,2"}