이 페이지는 Cloud Translation API를 통해 번역되었습니다.

클라이언트 라이브러리 빌드

소개

Google API 검색 서비스를 사용하여 Google API에서 사용할 수 있는 다양한 도구를 빌드할 수 있습니다. 하지만 검색 문서의 주요 목적은 Google에서 다양한 프로그래밍 언어로 클라이언트 라이브러리를 만들 수 있도록 하는 것입니다. 이 섹션에서는 Google API용 맞춤 클라이언트 라이브러리를 빌드하는 방법을 설명합니다.

안정적인 전체 클라이언트 라이브러리는 개발하는 데 몇 개월이 걸릴 수 있는 복잡한 도구입니다. 그러나 Google API를 위한 간단한 클라이언트 라이브러리를 빌드하는 방법에 대한 일반적인 안내는 다음과 같이 간단한 세 단계로 나눌 수 있습니다.

검색 문서 가져오기 및 API 노출 영역 구성
요청 작성
전화 걸기 및 응답 가져오기

이러한 단계에 대해서는 다음 섹션에서 더 자세히 설명합니다. 예시 섹션의 간단한 API 클라이언트 샘플을 보고 이러한 안내가 코드에 어떻게 매핑되는지 확인할 수 있습니다.

1단계: 검색 문서 가져오기

클라이언트 라이브러리를 구현하기 전에 개발 경로를 진행하는 방법에 영향을 주는 몇 가지 기본 요구사항이 있습니다. 예를 들어 원하는 프로그래밍 언어를 입력할 수도 있고 입력할 수 없습니다. 입력할 경우 정적 또는 동적으로 입력할 수 있습니다. 컴파일되거나 해석될 수 있습니다. 이러한 요구사항은 검색 문서를 사용하고 사용하기 위한 접근 방식을 안내합니다.

첫 번째 개발 작업은 검색 문서를 가져오는 것입니다. 문서를 가져오는 정확한 시간에 대한 전략은 지정한 요구사항에 따라 결정됩니다. 예를 들어, 정적 입력 유형의 언어로 검색 문서를 조기에 가져온 다음 코드를 생성하여 검색 문서에 설명된 특정 API를 처리할 수 있습니다. 타이핑된 언어의 경우 일부 코드를 생성하고 컴파일된 라이브러리를 빌드할 수 있습니다. 동적으로 형식이 지정된 언어의 경우, 프로그래밍 표면이 사용될 때 즉석에서 API에 접속하도록 프로그래밍 구조를 느리게 구성할 수 있습니다.

2단계: 요청 작성

요청 작성에는 다음 두 단계가 포함됩니다.

요청 본문 작성
요청 URL 구성

요청 본문이 있는 경우 언어에 적합한 표현에서 올바른 전송 형식으로 변환해야 합니다. 예를 들어 자바 클라이언트 라이브러리에는 각 요청 유형의 클래스가 요청 데이터의 유형 안전 조작을 허용하고 JSON으로 직렬화할 수 있습니다.

요청 URL을 구성하는 과정은 조금 더 복잡합니다.

API에서 각 메서드의 path 속성은 URI Template v04 구문을 사용합니다. 이 속성에는 중괄호로 묶인 변수가 포함될 수 있습니다. 다음은 변수가 포함된 path 속성의 예입니다.

/example/path/var

위 경로에서 var은 변수입니다. 이 변수의 값은 이 메서드에 대한 검색 문서의 parameters 섹션에서 가져옵니다. 각 변수 이름은 parameters 객체에 상응하는 값을 갖습니다. 위의 예시에서는 parameters 섹션에 var라는 매개변수가 있습니다 (그리고 location 속성이 path이며 경로 변수임을 나타냅니다).

요청할 때 var 값을 URL로 대체해야 합니다. 예를 들어 라이브러리 사용자가 var 값을 foo 값으로 설정하는 경우 새 URL은 /example/path/foo이 됩니다.

또한 path 속성은 상대 URI입니다. 절대 URI를 계산하려면 다음 단계를 따르세요.

검색 문서의 최상위 수준에서 rootUrl 속성을 선택합니다.
예를 들어 Google Cloud Service Management API의 검색 문서에서 rootUrl 속성은 다음과 같습니다.

https://servicemanagement.googleapis.com/
탐색 문서의 최상위 수준에서 servicePath를 가져옵니다.
예를 들어 Google Cloud Service Management API의 검색 문서에 있는 servicePath 속성이 비어 있습니다.
다음과 같이 연결하여 다음을 얻을 수 있습니다.

https://servicemanagement.googleapis.com/
path 속성을 찾아 URI 템플릿으로 확장하고 해당 확장 결과를 이전 단계의 URI와 결합합니다.
예를 들어 Google Cloud Service Management API의 get 서비스 메서드에서 path 속성의 값은 v1/services/{serviceName}입니다. 따라서 메서드의 전체 URI는 다음과 같습니다.

https://servicemanagement.googleapis.com/v1/services/{serviceName}

Google Cloud Service Management API를 호출하려면 API 키가 필요합니다. 따라서 API 키를 적용한 후 API 검색 서비스의 서비스 정의를 가져오는 전체 URI는 다음과 같습니다.

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

3단계: 전화 걸기 및 응답 처리하기

요청을 보낸 후에는 응답을 적절한 언어 표현으로 역직렬화하여 발생할 수 있는 오류 조건(기본 HTTP 전송 및 API 서비스에서 생성된 오류 메시지 모두)을 처리해야 합니다. 오류 형식은 Google JSON 스타일 가이드의 일부로 문서화됩니다.

Examples

Google API 검색 서비스를 사용하여 구현된 클라이언트 라이브러리 및 도구의 구체적인 예는 라이브러리 및 샘플 문서를 참고하세요. 또한 다음 섹션에서는 API 클라이언트 라이브러리의 간단한 예를 제공합니다.

간단한 API 클라이언트

다음은 Python3로 작성된 매우 간단한 클라이언트 라이브러리의 예입니다 . 클라이언트는 Google Cloud Service Management API와 상호작용하기 위한 인터페이스를 빌드한 다음 그 인터페이스를 사용하여 API 검색 서비스의 서비스 정의를 가져옵니다.

경고: 아래 코드는 일반적인 클라이언트 라이브러리의 상당히 단순화된 버전입니다. 이 라이브러리는 클라이언트 라이브러리 빌드의 일부 측면을 보여주기 위해 제공된 불완전한 구현입니다. 프로덕션에 바로 사용할 수 있는 코드가 아닙니다.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

클라이언트의 주요 구성요소는 다음과 같습니다.

1단계: 검색 문서 가져오기
Google Cloud Service Management API의 검색 문서를 가져와 데이터 구조로 파싱합니다. Python은 동적으로 입력되는 언어이므로 런타임에 검색 문서를 가져올 수 있습니다.
2.a단계: 기본 URI를 구성합니다.
기본 URI가 계산됩니다.
2.b단계: 요청을 작성합니다.
컬렉션에 대한 메서드가 호출되면 URI 템플릿이 메서드에 전달된 매개변수로 확장되고, 위치가 query인 매개변수는 URL의 쿼리 매개변수에 입력됩니다. 마지막으로 검색 문서에 지정된 HTTP 메서드를 사용하여 구성된 URL로 요청이 전송됩니다.
3.a단계: 클라이언트 노출 영역을 빌드합니다.
클라이언트 노출 영역은 파싱된 탐색 문서 위로 재귀적으로 내림됩니다. methods 섹션의 각 메서드에 대해 새 메서드가 Collection 객체에 연결됩니다. 컬렉션이 중첩될 수 있으므로 resources을 찾아 찾은 다음 이에 대한 모든 구성원을 위한 Collection 객체를 재귀적으로 빌드합니다. 각 중첩된 컬렉션도 Collection 객체에 속성으로 첨부됩니다.
3.b단계: 클라이언트를 사용합니다.
빌드된 API 노출 영역이 사용되는 방식을 보여줍니다. 먼저 검색 문서에서 서비스 객체를 빌드한 다음 Google Cloud Service Management API를 통해 API 검색 서비스의 서비스 정의를 가져옵니다.