Annotationen und Syntax für Cloud Endpoints Frameworks

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, können Sie diese optional mit der Annotation @ApiMethod festlegen. Zum Konfigurieren dieser Annotationen legen Sie verschiedene Attribute fest, wie in den folgenden Tabellen gezeigt.

@Api: API-bezogene Annotationen

Die Annotation @Api konfiguriert die gesamte API und gilt für alle öffentlichen Methoden einer Klasse, sofern sie nicht von @ApiMethod überschrieben wird.

Informationen zum Überschreiben einer bestimmten @Api-Anmerkung für eine bestimmte Klasse innerhalb 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:
  • Er muss mit Kleinbuchstaben beginnen.
  • Er muss dem regulären Ausdruck [a-z]+[A-Za-z0-9]* entsprechen.
Wenn Sie 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:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

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. 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 Attribut 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 erstellt und zur Verwendung durch das Projekt benannt wird. 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

Mit der Annotation @ApiMethod können Sie anstelle der Standardeinstellungen der Annotationen @Api und @ApiClass eine andere API-Konfiguration angeben. 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:
  • Name: Ein Name, den Sie in der Annotation ApiLimitMetric angeben.
  • 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.
 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:
  • Er muss mit Kleinbuchstaben beginnen.
  • Er muss dem regulären Ausdruck [a-z]+[A-Za-z0-9]* entsprechen.
Wenn Sie 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:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(
    name = "sayHiUser",
    httpMethod = ApiMethod.HttpMethod.GET)
public MyBean sayHiUser(@Named("name") String name, User user)
    throws OAuthRequestException, IOException {
  MyBean response = new MyBean();
  response.setData("Hi, " + name + "(" + user.getEmail() + ")");

  return response;
}

Methoden mit einer Entität als Parameter sollten für Einfügungen HttpMethod.POST und für Aktualisierungen HttpMethod.PUT verwenden:

@ApiMethod(
    name = "mybean.insert",
    path = "mybean",
    httpMethod = ApiMethod.HttpMethod.POST
)
public void insertFoo(MyBean foo) {
}

@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:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

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 von Kontingenten für Ihre API erforderlich sind. Die vollständige Anleitung zum Konfigurieren von Kontingenten finden Sie unter Kontingente konfigurieren.

Sie weisen die Annotation @ApiLimitMetric dem Attribut limitDefinitions der API-bezogenen Annotationen zu. Für jede Methode, der Sie ein Kontingent zuweisen möchten, müssen Sie den Annotationen vom Typ @ApiMethod außerdem @ApiMetricCost hinzufügen.

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:
  • Verwenden Sie "Anfragen", wenn Sie nur einen Messwert haben.
  • Wenn Sie mehrere Messwerte haben, sollte jeder den Abfragetyp 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

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:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Setzen Sie das ownerDomain-Attribut auf Ihre eigene Unternehmensdomain und ownerNameauf 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. Eine ausführliche Beschreibung dieser Annotation finden Sie unter @ApiClass für abweichende Attribute in Klassen verwenden.

@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:


class Resp {
  private String foobar = "foobar";
  private String bin = "bin";

  @ApiResourceProperty
  private String visible = "nothidden";

  @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
  public String getBin() {
    return bin;
  }

  public void setBin(String bin) {
    this.bin = bin;
  }

  @ApiResourceProperty(name = "baz")
  public String getFoobar() {
    return foobar;
  }

  public void setFoobar(String foobar) {
    this.foobar = foobar;
  }
}

public Resp getResp() {
  return new Resp();
}

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:


@ApiTransformer(BarTransformer.class)
public class Bar {
  private final int x;
  private final int y;

  public Bar(int x, int y) {
    this.x = x;
    this.y = y;
  }

  public int getX() {
    return x;
  }

  public int getY() {
    return y;
  }
}

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:

public class BarTransformer implements Transformer<Bar, String> {
  public String transformTo(Bar in) {
    return in.getX() + "," + in.getY();
  }

  public Bar transformFrom(String in) {
    String[] xy = in.split(",");
    return new Bar(Integer.parseInt(xy[0]), Integer.parseInt(xy[1]));
  }
}

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"}