소개
이 문서는 클라이언트 라이브러리, IDE 플러그인, Google API와 상호작용하는 기타 도구를 작성하려는 개발자를 대상으로 합니다. Google API 검색 서비스를 사용하면 간단한 API를 통해 머신이 읽을 수 있는 다른 Google API 메타데이터를 노출하여 위의 모든 작업을 할 수 있습니다. 이 가이드에서는 검색 문서의 각 섹션에 대한 개요와 문서 사용 방법에 관한 유용한 팁을 제공합니다.
API에 대한 모든 호출은 SSL을 사용하는 인증되지 않은 JSON 기반 REST 요청 즉, URL이 https로 시작하는 요청입니다.
Google API 검색 서비스 개념에 익숙하지 않은 경우 코딩을 시작하기 전에 시작하기를 읽어야 합니다.
검색 문서 형식
이 섹션에서는 검색 문서를 간략하게 설명합니다.
아래 모든 예시에서는 Google Cloud Service Management API의 검색 문서를 사용합니다. 다음 GET 요청을 실행하여 Google Cloud Service Management API의 검색 문서를 로드할 수 있습니다.
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1디스커버리 문서의 형식에는 6가지 기본 카테고리에 해당하는 정보가 포함됩니다.
- API에 대한 기본 설명
- API에 대한 인증 정보입니다.
- API 데이터를 설명하는 리소스 및 스키마 세부정보
- API 메서드에 관한 세부정보입니다.
- API에서 지원하는 모든 맞춤 기능에 관한 정보입니다.
- API의 주요 요소를 설명하는 인라인 문서
이러한 각 탐색 문서 섹션은 아래에 설명되어 있습니다. 각 속성에 관한 자세한 내용은 참조 문서를 참고하세요.
기본 API 설명
검색 문서에는 API별 속성 집합이 포함되어 있습니다.
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
이러한 API 수준 속성에는 name, version, title, description 등 API의 특정 버전에 관한 세부정보가 포함됩니다. API 검색 서비스는 API에 액세스하기 위한 RESTful 메서드만 지원하므로 protocol는 항상 고정된 값 rest입니다.
servicePath 필드는 이 특정 API 버전의 경로 프리픽스를 나타냅니다.
인증
auth 섹션에는 API의 OAuth 2.0 인증 범위에 대한 세부정보가 포함되어 있습니다. OAuth 2.0에서 범위를 사용하는 방법을 자세히 알아보려면 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.
auth 섹션에는 중첩된 oauth2 및 scopes 섹션이 포함되어 있습니다. scopes 섹션은 범위 값에서 범위에 대한 자세한 세부정보로 이어지는 키/값 매핑입니다.
"auth": {
"oauth2": {
"scopes": {
"https://www.googleapis.com/auth/cloud-platform.read-only": {
"description": "View your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management.readonly": {
"description": "View your Google API service configuration"
},
"https://www.googleapis.com/auth/cloud-platform": {
"description": "View and manage your data across Google Cloud Platform services"
},
"https://www.googleapis.com/auth/service.management": {
"description": "Manage your Google API service configuration"
}
}
}
}
auth 섹션은 특정 API의 범위만 정의합니다. 이러한 범위가 API 메서드와 연결되는 방식을 알아보려면 아래 메서드 섹션을 참고하세요.
리소스 및 스키마
API 작업은 resources라는 데이터 객체에서 작동합니다. 탐색 문서는 리소스 개념을 기반으로 합니다. 각 검색 문서에는 API와 연결된 모든 리소스를 그룹화하는 최상위 resources 섹션이 있습니다. 예를 들어 Google Cloud Service Management API에는 services 리소스와 최상위 리소스 resources에 operations 리소스가 있으며, services 리소스에는 configs, rollouts, consumers의 세 가지 하위 리소스가 있습니다.
"resources": {
"services": {
// Methods and sub-resources associated with the services resource
"configs": {
// Methods and sub-resources associated with the services.configs resource
},
"rollouts": {
// Methods and sub-resources associated with the services.rollouts resource
},
"consumers": {
// Methods and sub-resources associated with the services.consumers resource
}
},
"operations": {
// Methods and sub-resources associated with the operations resource
}
}
각 리소스 섹션 내부에는 해당 리소스와 연결된 메서드가 있습니다. 예를 들어 Google Cloud Service Management API에는 services.rollouts 리소스와 연결된 세 가지 메서드 get, list, create가 있습니다.
스키마는 API의 리소스가 어떤 모습인지 알려줍니다. 각 검색 문서에는 객체에 대한 스키마 ID의 이름/값 쌍이 포함된 최상위 schemas 섹션이 있습니다. 스키마 ID는 API별로 고유하며 검색 문서의 methods 섹션에서 스키마를 고유하게 식별하는 데 사용됩니다.
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
API 검색 서비스는 스키마 표현에 JSON 스키마 initial-03을 사용합니다. 다음은 실제 응답 리소스와 함께 Url 리소스의 JSON 스키마 스니펫입니다.
| 롤아웃 리소스 JSON 스키마: | 실제 출시 리소스 응답: |
{
"Rollout": {
"id": "Rollout",
"type": "object",
"description": "...",
"properties": {
"serviceName": {
"type": "string",
"description": "..."
},
"rolloutId": {
"type": "string",
"description": "..."
},
"status": {
"type": "string",
"enum": [
"ROLLOUT_STATUS_UNSPECIFIED",
"IN_PROGRESS",
"SUCCESS",
"CANCELLED",
"FAILED",
"PENDING",
"FAILED_ROLLED_BACK"
],
"enumDescriptions": [
...
],
"description": "..."
},
"trafficPercentStrategy": {
"$ref": "TrafficPercentStrategy",
"description": "..."
},
"deleteServiceStrategy": { ... },
"createTime": { ... },
"createdBy": { ... }
}
}
}
|
{
"serviceName": "discovery.googleapis.com",
"rolloutId": "2020-01-01R0",
"status": "SUCCESS",
"trafficPercentStrategy":{
"precentages":{
"2019-12-01R0": 70.00,
"2019-11-01R0": 30.00
}
}
}
|
굵게 표시된 필드는 JSON 스키마와 실제 응답 간의 매핑을 보여줍니다.
스키마에는 다른 스키마에 대한 참조도 포함될 수 있습니다. 클라이언트 라이브러리를 빌드하고 있다면 데이터 모델 클래스에서 API 객체를 효과적으로 모델링하는 데 도움이 됩니다. 위의 Rollout 예에서 trafficPercentStrategy 속성은 실제로 ID가 TrafficPercentStrategy인 스키마의 참조입니다. schemas 섹션에 TrafficPercentStrategy 스키마가 있습니다. 이 스키마의 값은 Rollout 리소스의 trafficPercentStrategy 속성으로 대체할 수 있습니다. $ref 구문은 JSON 스키마 사양에서 가져옵니다.
요청 및 응답 본문을 표시할 때 메서드가 스키마를 참조할 수도 있습니다. 자세한 내용은 메서드 섹션을 참고하세요.
메서드
탐색 문서의 핵심은 메서드를 중심으로 빌드되었습니다. 메서드는 API에서 수행할 수 있는 작업입니다. methods 섹션은 최상위 수준 (API 수준 메서드라고 함)이나 resources 수준을 포함하여 검색 문서의 다양한 영역에서 찾을 수 있습니다.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
API에는 API 수준의 메서드가 있을 수도 있지만 리소스에는 methods 섹션이 있어야 합니다.
각 methods 섹션은 메서드 이름에서 그 메서드에 관한 다른 세부정보로 이어지는 키/값 매핑입니다. 아래 예에서는 세 가지 메서드 get, list, create를 설명합니다.
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
마지막으로 각 메서드 섹션에서 이 메서드에 관한 다양한 속성을 자세히 설명합니다. 다음은 get 메서드의 예입니다.
"get": {
"id": "servicemanagement.services.rollouts.get",
"path": "v1/services/{serviceName}/rollouts/{rolloutId}",
"flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
"httpMethod": "GET",
"description": "Gets a service configuration rollout.",
"response": { "$ref": "Rollout" },
"parameters": { // parameters related to the method },
"parameterOrder": [ // parameter order related to the method ],
"scopes": [ // OAuth 2.0 scopes applicable to this method ],
"mediaUpload": { // optional media upload information },
},
이 섹션에는 메서드를 식별하는 고유한 ID, 사용할 httpMethod, 메서드의 path과 같은 일반적인 메서드 세부정보가 포함되어 있습니다. path 속성을 사용하여 전체 메서드 URL을 계산하는 방법에 관한 자세한 내용은 요청 작성 섹션을 참고하세요. 이러한 일반적인 메서드 속성 외에도 메서드를 검색 문서의 다른 섹션과 연결하는 몇 가지 속성이 있습니다.
범위
이 문서의 앞부분에 정의된 auth 섹션에는 특정 API에서 지원하는 모든 범위에 대한 정보가 포함되어 있습니다. 메서드가 이러한 범위 중 하나를 지원하는 경우 범위 배열이 포함됩니다. 이 배열에는 메서드에서 지원하는 각 범위에 대한 한 개의 항목이 있습니다. 예를 들어 Google Cloud Service Management API get 메서드의 scopes 섹션은 다음과 같습니다.
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
애플리케이션에서 사용할 인증 범위는 어떤 메서드를 호출할지, 메서드와 함께 어떤 매개변수가 전송되는지 등 다양한 요인에 따라 달라집니다. 따라서 어느 범위를 사용할지 결정하는 것은 개발자의 몫입니다. 검색에는 메서드에 유효한 범위만 기록됩니다.
요청 및 응답
메서드에 요청 또는 응답 본문이 있는 경우 각각 request 또는 response 섹션에 설명되어 있습니다. 위의 get 예에서 메서드에는 response 본문이 있습니다.
"response": {
"$ref": "Rollout"
}
위의 구문은 응답 본문이 ID가 Rollout인 JSON 스키마로 정의되었음을 나타냅니다. 이 스키마는 최상위 스키마 섹션에서 찾을 수 있습니다. 요청 본문과 응답 본문 모두 $ref 참조를 사용하여 스키마를 참조합니다.
매개변수
메서드에 사용자가 지정해야 하는 매개변수가 있으면 이러한 매개변수는 메서드 수준 parameters 섹션에 설명되어 있습니다. 이 섹션에는 매개변수 이름에 대한 자세한 키-값 매핑이 포함되어 있습니다.
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
위 예시에는 get 메서드에 관한 매개변수 두 개(serviceName, rolloutId)가 있습니다. 매개변수는 path 또는 URL query에 들어갈 수 있습니다. location 속성은 클라이언트 라이브러리가 매개변수를 배치해야 하는 위치를 나타냅니다.
매개변수 데이터 type(강력한 유형의 언어에 유용), 매개변수가 required인지 여부, 매개변수가 enum인지 여부를 비롯한 다른 여러 속성이 있습니다. 속성에 대한 자세한 내용은 참조 가이드를 참고하세요.
매개변수 순서
클라이언트 라이브러리가 인터페이스를 구조화하는 방법에는 여러 가지가 있습니다. 한 가지 방법은 메서드 서명에 각 API 매개변수가 있는 메서드를 포함하는 것입니다. 그러나 JSON은 순서가 지정되지 않은 형식이므로 메서드 서명에서 매개변수를 정렬하는 방법을 프로그래매틱 방식으로 알기 어렵습니다. parameterOrder 배열은 요청을 위한 고정된 매개변수 순서를 제공합니다. 배열에는 각 매개변수의 이름이 중요도 순으로 나열됩니다. 배열 또는 쿼리 매개변수를 포함할 수 있지만 배열의 모든 매개변수는 필수입니다. 위의 예에서 자바 메서드 서명은 다음과 같을 수 있습니다.
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);parameterOrder 배열의 첫 번째 값인 serviceName도 메서드 서명의 첫 번째 요소입니다. parameterOrder 배열에 다른 매개변수가 있다면 serviceName 매개변수 다음에 옵니다. parameterOrder 배열에는 필수 매개변수만 포함되어 있으므로 사용자가 선택적 매개변수를 지정할 수 있는 방법을 포함하는 것이 좋습니다. 위의 예에서는 optionalParameters 맵을 사용합니다.
미디어 업로드
메서드에서 이미지, 오디오 또는 동영상과 같은 미디어 업로드를 지원하는 경우 미디어 업로드를 지원하는 위치 및 프로토콜은 mediaUpload 섹션에 설명되어 있습니다. 이 섹션에는 지원되는 업로드 프로토콜에 대한 세부정보와 업로드할 수 있는 미디어 종류에 대한 정보가 포함되어 있습니다.
"supportsMediaUpload": true,
"mediaUpload": {
"accept": [
"image/*"
],
"maxSize": "10MB",
"protocols": {
"simple": {
"multipart": true,
"path": "/upload/storage/v1beta1/b/{bucket}/o"
},
"resumable": {
"multipart": true,
"path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
}
}
}
위의 예에서 supportsMediaUpload 속성은 메서드가 미디어 업로드를 지원하는지 여부를 결정하는 부울 값입니다. 값이 참인 경우 mediaUpload 섹션은 업로드할 수 있는 미디어의 종류를 문서화합니다.
accept 속성은 업로드할 수 있는 MIME 유형을 결정하는 미디어 범위 목록입니다. 위 예시에 표시된 엔드포인트는 모든 이미지 형식을 허용합니다.
maxSize 속성에 업로드 가능한 최대 크기가 있습니다. 값은 MB, GB 또는 TB 단위의 문자열입니다. 위 예에서 업로드는 최대 10MB로 제한됩니다. 이 값은 해당 API의 개별 사용자 남아 있는 저장용량을 반영하지 않습니다. 따라서 업로드가 maxSize보다 적더라도 클라이언트 라이브러리가 공간 부족으로 인해 실패한 업로드를 처리할 수 있도록 준비해야 합니다.
protocols 섹션에는 메서드가 지원하는 업로드 프로토콜이 나열됩니다. simple 프로토콜은 단일 HTTP 요청으로 지정된 엔드포인트에 미디어를 POST하는 것입니다. resumable 프로토콜은 path URI에 지정된 엔드포인트가 재개 가능한 업로드 프로토콜을 지원한다는 것을 의미합니다. multipart 속성이 true이면 엔드포인트가 멀티파트 업로드를 허용합니다. 즉, JSON 요청과 미디어가 모두 상호/관련 본문에 함께 래핑되어 함께 전송될 수 있습니다. simple 및 resumable 프로토콜은 모두 멀티파트 업로드를 지원할 수 있습니다.
path 속성은 URI 템플릿이며 요청 작성 섹션에 설명된 대로 메서드의 path 속성과 마찬가지로 확장되어야 합니다.
미디어 다운로드
메서드가 이미지, 오디오 또는 동영상과 같은 미디어 다운로드를 지원하는 경우 supportsMediaDownload 매개변수로 표시됩니다.
"supportsMediaDownload": true,
미디어를 다운로드할 때 요청 URL에서 alt 쿼리 매개변수를 media로 설정해야 합니다.
API 메서드의 useMediaDownloadService 속성이 true인 경우 servicePath 앞에 /download를 삽입하여 리디렉션을 피합니다. 예를 들어 servicePath와 path의 연결이 /youtube/v3/captions/{id}이면 다운로드 경로는 /download/youtube/v3/captions/{id}입니다. useMediaDownloadService이 false인 경우에도 /download로 미디어 다운로드 URL을 구성하는 것이 좋습니다.
일반 매개변수
최상위 검색 문서에는 parameters 속성이 포함되어 있습니다. 이 섹션은 각 메서드의 매개변수 섹션과 비슷하지만, API의 모든 메서드에 적용할 수 있습니다.
예를 들어 Google Cloud Service Management API의 get, insert 또는 list 메서드는 요청 매개변수에 prettyPrint 매개변수를 포함할 수 있습니다. 그러면 이러한 모든 메서드에 대한 응답의 사람이 인식할 수 있는 형식으로 지정됩니다. 다음은 일반적인 매개변수 목록입니다.
| 매개변수 | 의미 | 참고 | 적용 대상 |
|---|---|---|---|
access_token |
현재 사용자의 OAuth 2.0 토큰입니다. |
|
|
alt |
응답용 데이터 형식입니다. |
|
|
callback |
콜백 함수입니다. |
| |
fields |
응답에 포함할 필드의 하위 집합을 지정하는 선택기입니다. |
|
|
key |
API 키입니다. (필수*) | ||
prettyPrint |
ID와 줄바꿈이 포함된 응답을 반환합니다. |
|
|
quotaUser |
userIp의 대체 매개변수입니다. |
|
|
userIp |
API 호출을 실행하는 최종 사용자의 IP 주소입니다. |
|
기능
API가 나머지 탐색 문서 범위에서 벗어나는 맞춤 기능을 지원하는 경우도 있습니다. features 배열에서 수집됩니다. 기능 배열에는 API에서 지원하는 각 특수 기능의 문자열 라벨이 포함되어 있습니다. 현재는 dataWrapper가 유일하게 지원되는 기능이지만 향후 다른 기능도 지원될 수 있습니다.
"features": dataWrapper
dataWrapper 기능은 API에 대한 모든 요청과 응답이 data JSON 객체로 래핑된다는 것을 나타냅니다. 이는 이전 Google API의 기능이지만 앞으로 지원이 중단됩니다. Moderator v1 및 Translate v2 API는 dataWrapper 기능을 지원합니다.
클라이언트 라이브러리 개발자가 API에서 'dataWrapper&' 기능을 지원하는 경우 다음 단계를 따라야 합니다.
- 요청 시: 요청 리소스를
dataJSON 객체로 래핑합니다. - 응답 시:
dataJSON 객체 내에서 리소스를 찾습니다.
검색 문서의 스키마에는 데이터 래퍼가 포함되어 있지 않으므로 명시적으로 추가 및 삭제해야 합니다. 예를 들어, "Foo"라는 리소스가 포함된 API가 있다고 가정해 보겠습니다.
{
"id": 1,
"foo": "bar"
}
API를 사용하여 이 리소스를 삽입하기 전에 데이터 요소에 래핑해야 합니다.
{
"data": {
"id": 1,
"foo": "bar"
}
}
다른 한편으로, API에서 응답을 받을 때 데이터 래퍼도 포함됩니다.
{
"data": {
"id": 1,
"foo": "bar"
}
}
스키마에서 정의한 리소스를 가져오려면 데이터 래퍼를 삭제해야 합니다.
{
"id": 1,
"foo": "bar"
}
인라인 문서
각 검색 문서에는 API에 대한 인라인 문서를 제공하는 여러 description 필드가 주석 처리됩니다. description 필드는 다음 API 요소에서 확인할 수 있습니다.
- API 자체
- OAuth 범위
- 리소스 스키마
- API 메서드
- 메서드 매개변수
- 특정 매개변수에 허용되는 값
이러한 필드는 Google API 검색 서비스를 사용하여 사람이 읽을 수 있는 클라이언트 라이브러리 문서(예: JavaDoc)를 생성하려는 경우에 특히 유용합니다.