Cloud Endpoints 프레임워크 주석 및 구문

Endpoints 프레임워크 주석은 API 구성, 메소드, 매개변수, Endpoint의 속성과 동작을 정의하는 기타 중요한 세부정보를 설명합니다.

Maven 프로젝트를 사용하여 주석을 추가하는 방법에 대한 자세한 내용은 코드 작성 및 주석 추가를 참조하세요. Maven App Engine Cloud Endpoints 아티팩트는 백엔드 API를 생성 및 빌드하고 이를 사용하여 클라이언트 라이브러리를 생성할 수 있도록 제공됩니다.

전체 API의 구성과 동작을 지정하는 주석(API에 노출된 모든 클래스와 이러한 클래스의 노출된 모든 메서드에 영향을 줌)은 @Api입니다. @Api 주석이 있는 클래스의 공개, 비정적, 비브리지 메서드는 모두 공개 API에 노출됩니다.

특정 메서드를 위한 특수 API 구성이 필요한 경우 @ApiMethod를 사용하여 메서드별로 설정을 구성할 수 있습니다. 아래 표에 나열된 다양한 속성을 설정하여 이러한 주석을 구성합니다.

@Api: API-scoped annotations

주석 @Api는 전체 API를 구성하며 @ApiMethod에 의해 재정의되지 않는 한 클래스의 모든 공개 메서드에 적용됩니다.

API 내의 특정 클래스에 대해 지정된 @Api 주석을 재정의하려면 @ApiClass와 @ApiReference를 참조하세요.

필수 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

import com.google.api.server.spi.config.Api;

속성

샘플@Api 주석

이 주석은 클래스 정의 앞에 위치합니다.

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

고객 ID 및 대상

OAuth2 인증의 경우 특정 클라이언트 ID에 OAuth2 토큰이 발급되므로 클라이언트 ID를 사용하여 API에 대한 액세스를 제한할 수 있습니다. Google Cloud 콘솔에서 Android 애플리케이션을 등록할 때 이에 대한 클라이언트 ID를 만듭니다. 이 클라이언트 ID가 인증을 위해 Google로부터 OAuth2 토큰을 요청하는 ID입니다. 백엔드 API가 인증으로 보호되면 OAuth2 액세스 토큰이 전송되어 Endpoints에서 열리고, 토큰에서 클라이언트 ID가 추출된 다음 백엔드의 선언된 허용 가능 클라이언트 ID 목록(clientIds 목록)과 비교됩니다.

Endpoints API에서 호출자를 인증하게 하려면 토큰을 요청하도록 허용된 clientIds 목록을 제공해야 합니다. 이 목록은 웹 또는 Android 클라이언트용으로 Google Cloud 콘솔을 통해 가져온 모든 클라이언트 ID로 구성되어야 합니다. 즉, API 빌드 시 클라이언트를 알고 있어야 합니다. 빈 목록({})을 지정하면 클라이언트가 인증으로 보호되는 메서드에 액세스할 수 없습니다.

clientIds 속성을 사용하는 상태에서 Google API 탐색기로 API에 대한 인증된 호출을 테스트하려면 clientIds 목록의 클라이언트 ID를 제공해야 하며 사용할 값은 com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID입니다.

대상 정보

clientIds 목록은 승인되지 않은 클라이언트로부터 백엔드 API를 보호합니다. 그러나 의도한 백엔드 API에만 인증 토큰이 작동하도록 클라이언트 보호를 강화해야 합니다. Android 클라이언트의 경우 이 메커니즘은 audiences 속성입니다. 이 속성에 백엔드 API의 클라이언트 ID를 지정합니다.

Google Cloud 콘솔 프로젝트를 만들 때 기본 클라이언트 ID가 자동으로 생성되고 프로젝트에서 사용할 수 있도록 이름이 지정됩니다. App Engine에 백엔드 API를 업로드하면 해당 클라이언트 ID가 사용됩니다. 이는 API 인증에 언급된 웹 클라이언트 ID입니다.

@ApiMethod: 메서드 범위 주석

주석 @ApiMethod는 @Api 또는 @ApiClass 주석에서 제공하는 기본값이 아닌 다른 API 구성을 제공하는 데 사용됩니다. 이는 선택사항입니다. @Api 주석이 있는 클래스의 모든 공개, 비정적, 비브리지 메서드는 @ApiMethod 주석 유무와 관계없이 API에 노출됩니다.

이 주석 내의 속성을 사용하면 단일 API 메서드의 세부정보를 구성할 수 있습니다. 같은 속성이 @Api와 @ApiMethod에 지정되면 @ApiMethod가 우선합니다.

필수 항목 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

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;

속성

샘플 @ApiMethod 주석

이 주석은 클래스 내부의 메서드 정의 앞에 위치합니다.

/** 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;
}

항목을 매개변수로 사용하는 메서드는 HttpMethod.POST(삽입 작업용) 또는 HttpMethod.PUT(업데이트 작업용)을 사용해야 합니다.

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

@Named

@Named 주석은 서버 측 메서드에 전달되는 모든 비항목 유형 매개변수에 필요합니다. 이 주석은 여기에 삽입되는 요청에서 매개변수 이름을 나타냅니다. @Named 주석이 달리지 않은 매개변수는 전체 요청 객체와 함께 삽입됩니다.

필수 항목 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

import javax.inject.Named;

이 샘플은 @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;
}

여기서 @Named는 요청에 id 매개변수만 삽입되도록 지정합니다.

@ApiLimitMetric

이 섹션에서는 API의 할당량을 정의하는 데 필요한 주석을 설명합니다. 할당량 설정에 필요한 모든 단계는 할당량 구성을 참조하세요.

API 범위 주석의 limitDefinitions 속성에 @ApiLimitMetric 주석을 할당합니다. 또한 할당량을 적용하려는 각 메서드의 @ApiMethod 주석에 @ApiMetricCost를 추가해야 합니다.

필수 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

import com.google.api.server.spi.config.ApiLimitMetric;

속성

예

limitDefinitions = {
      @ApiLimitMetric(
        name = "read-requests",
        displayName = "Read requests",
        limit = 1000),
      @ApiLimitMetric(
        name = "write-requests",
        displayName = "Write requests",
        limit = 50),
    }

@ApiNamespace

@ApiNamespace 주석을 사용하면 생성된 클라이언트 라이브러리가 클라이언트 라이브러리 생성 중 구성된 기본값이 아닌 사용자가 지정하는 네임스페이스를 갖게 됩니다.

기본적으로 이 주석을 사용하지 않을 경우 사용되는 네임스페이스는 your-project-id.appspot.com의 역입니다. 즉, 패키지 경로는 com.appspot.your-project-id.yourApi입니다.

@Api 주석 내에 @ApiNamespace 주석을 제공하여 기본 네임스페이스를 변경할 수 있습니다.

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

ownerDomain 속성을 회사 도메인으로 설정하고 ownerName을 회사 이름으로 설정합니다(예: your-company.com). 그러면 ownerDomain의 역이 com.your-company.yourApi 패키지 경로에 사용됩니다.

필요에 따라 packagePath 속성을 사용하여 추가 범위를 제공할 수 있습니다. 예를 들어 packagePath를 cloud로 설정하면 com.your-company.cloud.yourApi가 클라이언트 라이브러리에 패키지 경로로 사용됩니다. / 구분 기호를 제공하여 패키지 경로에 더 많은 값을 추가할 수 있습니다(예: packagePath="cloud/platform").

@Nullable

이 주석은 메서드의 매개변수가 선택사항이므로 쿼리 매개변수임을 나타냅니다. @Nullable은 @Named 매개변수에만 사용할 수 있습니다.

@ApiClass

멀티클래스 API에서 @ApiClass를 사용하면 지정된 클래스에 다른 속성을 지정할 수 있습니다. 이는 @Api 구성에서 해당 속성을 재정의합니다. 이 주석에 대한 자세한 내용은 클래스 간 달라질 수 있는 속성에 @ApiClass 사용을 참조하세요.

@ApiReference

멀티클래스 API에서 @ApiReference를 사용하면 주석 상속의 대체 메서드를 제공할 수 있습니다. 이 주석에 대한 자세한 내용은 @ApiReference 상속 사용을 참조하세요.

@ApiResourceProperty

@ApiResourceProperty는 API에 리소스 속성이 노출되는 방식에 대한 제어를 제공합니다. 속성 getter 또는 setter에 이를 사용하여 API 리소스의 속성을 생략할 수 있습니다. 또한 필드가 비공개인 경우 필드 자체에 이를 사용하여 API에 이를 노출시킬 수 있습니다. 이 주석을 사용하여 API 리소스에서 속성 이름을 변경할 수도 있습니다.

필수 항목 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;

속성

@ApiResourceProperty를 사용한 샘플 클래스

다음 스니펫은 @ApiResourceProperty 주석이 달린 속성 getter가 있는 클래스를 보여줍니다.

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();
}

앞의 코드 스니펫에서는 @ApiResourceProperty가 bin 속성의 getBin getter에 적용됩니다. 또한 ignored 속성 설정은 Endpoints Frameworks에 API 리소스의 이 속성을 무시하도록 지시합니다.

@ApiResourceProperty는 getter 또는 setter가 없는 비공개 필드 visible에도 적용됩니다. 이 주석을 사용하면 이 필드가 API 리소스의 속성으로 노출됩니다.

동일한 스니펫에서 @ApiResourceProperty는 foobar 속성 값을 반환하는 다른 getter인 getFoobar에도 적용됩니다. 이 주석의 name 속성은 Endpoints Frameworks에 API 리소스의 속성 이름을 변경하도록 지시합니다. 속성 값 자체는 변경되지 않습니다.

앞의 스니펫 예시에서 Resp 객체의 JSON 표현은 다음과 유사합니다.

{"baz": "foobar", "visible": "nothidden"}

@ApiTransformer

@ApiTransformer 주석은 다른 유형과의 변환을 통해 Endpoints에 유형이 노출되는 방식을 맞춤설정합니다. 지정된 변환기는 com.google.api.server.spi.config.Transformer의 구현이어야 합니다.

클래스에서 @ApiTransformer 주석을 사용하는 것이 변환기를 지정하는 가장 좋은 방법입니다. 그러나 @Api 주석의 transformer 속성에 커스텀 변환기를 지정할 수도 있습니다.

필수 항목 가져오기

이 기능을 사용하려면 다음 가져오기가 필요합니다.

import com.google.api.server.spi.config.ApiTransformer;

@ApiTransformer를 사용한 샘플 클래스

다음 스니펫은 @ApiTransformer 주석이 달린 클래스를 보여줍니다.

@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;
  }
}

이 클래스는 BarTransformer 클래스에 의해 변환됩니다.

샘플 Endpoints 변환기 클래스

다음 스니펫은 BarTransformer라는 샘플 변환기 클래스를 보여 줍니다. 이는 앞의 스니펫에서 @ApiTransformer가 참조하는 변환기입니다.

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]));
  }
}

위의 변환기가 없으며 Bar 유형의 속성 bar를 가진 객체가 있는 경우 해당 객체는 다음과 같이 표현됩니다.

{"bar": {"x": 1, "y": 2}}

변환기가 있는 경우 객체는 다음과 같이 표현됩니다.

{"bar": "1,2"}