Discovery API 사용

이 문서는 Google API와 상호작용하기 위해 클라이언트 라이브러리, IDE 플러그인, 기타 도구를 작성하려는 개발자를 대상으로 합니다. Google API 탐색 서비스는 간단한 API를 통해 머신이 읽을 수 있는 다른 Google API에 대한 메타데이터를 노출하여 위의 모든 작업을 수행할 수 있습니다. 이 가이드에서는 탐색 문서의 각 섹션에 대한 개요와 문서 사용 방법에 대한 유용한 팁을 제공합니다.

모든 API 호출은 인증되지 않은 JSON 기반 REST 요청이며, SSL을 사용합니다. 즉, URL이 https로 시작합니다.

탐색 문서 형식

이 섹션에서는 탐색 문서의 개요를 제공합니다.

아래의 모든 예시에서는 Service Usage API의 탐색 문서를 사용합니다. 다음 GET 요청을 실행하면 Service Usage API의 탐색 문서를 로드할 수 있습니다.

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

탐색 문서의 형식에는 6가지 주요 카테고리로 나뉘는 정보가 포함됩니다.

API에 대한 기본 설명
API에 대한 인증 정보
API의 데이터를 기술하는 리소스 및 스키마 세부정보
API 메서드에 대한 세부정보
API에서 지원하는 커스텀 특성에 대한 정보
API의 핵심 요소를 설명하는 인라인 문서

각 탐색 문서 섹션은 아래에 설명되어 있습니다.

기본 API 설명

탐색 문서에는 API별 속성 세트가 포함됩니다. 다음 속성은 반드시 이 순서로 표시되거나 탐색 문서의 동일한 섹션에 표시되지 않습니다.

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

이러한 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": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

auth 섹션은 특정 API에 대한 범위만 정의합니다. 이러한 범위가 API 메서드와 연결되는 방식을 이해하려면 아래의 메서드 섹션을 참조하세요.

리소스 및 스키마

API 작업은 resources라는 데이터 객체에서 수행됩니다. 탐색 문서는 리소스 개념을 기준으로 빌드됩니다. 각 탐색 문서에는 API와 관련된 모든 리소스를 그룹화하는 최상위 resources 섹션이 있습니다. 예를 들어 Service Usage API에는 최상위 resources 아래에 services 리소스와 operations 리소스가 있습니다.

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

각 리소스 섹션에는 해당 리소스와 연결된 메서드가 있습니다. 예를 들어 Service Usage API에는 services 리소스와 연결된 6개의 메서드 get, enable, disable, batchGet, batchEnable, list가 있습니다.

스키마는 API에 있는 리소스가 어떤 모습인지 알려줍니다. 각 탐색 문서에는 객체에 대한 스키마 ID의 이름/값 쌍이 포함된 최상위 schemas 섹션이 있습니다. 스키마 ID는 API별로 고유하며 탐색 문서의 methods 섹션에서 스키마를 고유하게 식별하는 데 사용됩니다. 예를 들어 Service Usage API 탐색 문서의 몇 가지 스키마는 다음과 같습니다.

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

API 탐색 서비스는 스키마 표현에 JSON 스키마 초안-03을 사용합니다. 다음은 참조하는 GoogleApiServiceusagev1Service와 함께 EnableServiceResponse 리소스에 대한 JSON 스키마 스니펫입니다. 이러한 스키마와 함께 Pub/Sub API(pubsub.googleapis.com)를 사용 설정하기 위한 요청의 실제 응답의 일부입니다.

EnableServiceResponse 리소스 JSON 스키마: 서비스 사용 설정에 대한 실제 응답:

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

굵게 표시된 필드는 JSON 스키마와 실제 응답 간의 매핑을 보여줍니다.

이 예시에서와 같이 스키마는 다른 스키마에 대한 참조를 포함할 수 있습니다. 클라이언트 라이브러리를 빌드할 때 이 참조를 사용하면 데이터 모델 클래스에서 API의 객체를 효과적으로 모델링할 수 있습니다. 위의 EnableServiceResponse 예시에서 service 속성은 ID가 GoogleApiServiceusageV1Service인 스키마에 대한 참조이며, Service Usage API 탐색 문서의 또 다른 스키마입니다. EnableServiceResponse 리소스의 GoogleApiServiceusageV1Service 속성을 GoogleApiServiceusageV1Service 스키마 값으로 대체할 수 있습니다($ref 구문은 JSON 스키마 사양 참조).

메서드는 요청 및 응답 본문을 나타낼 때 스키마를 참조할 수도 있습니다. 자세한 내용은 메서드 섹션을 참조하세요.

메서드

탐색 문서의 핵심은 메서드를 기반으로 빌드됩니다. 메서드는 API에서 수행할 수 있는 작업입니다. 최상위 수준(API 수준 메서드 호출) 또는 resources 수준을 포함하여 탐색 문서의 다양한 영역에서 methods 섹션을 찾을 수 있습니다.

"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, enable, disable의 3가지 메서드를 설명합니다.

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

마지막으로 각 메서드의 섹션에서는 해당 메서드의 다양한 속성에 대해 자세히 설명합니다. 다음은 enable 메서드의 예입니다.

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

이 섹션에는 메서드를 식별하는 고유 ID, 사용할 httpMethod, 메서드의 path와 같은 일반적인 메서드 세부정보가 포함되어 있습니다. path 속성을 사용하여 전체 메서드 URL을 계산하는 방법에 대한 자세한 내용은 요청 작성 섹션을 참조하세요. 이러한 일반적인 메서드 속성 외에도 탐색 문서의 다른 섹션과 메서드를 연결하는 몇 가지 속성이 있습니다.

범위

이 문서의 앞부분에서 정의된 auth 섹션에는 특정 API에서 지원되는 모든 범위에 대한 정보가 포함되어 있습니다. 메서드가 이러한 범위 중 하나를 지원하면 범위 배열이 생성됩니다. 이 배열에는 메서드에서 지원되는 각 범위마다 하나의 항목이 있습니다.

애플리케이션에서 사용할 인증 범위를 선택하는 방법은 호출되는 메서드, 메서드와 함께 전송되는 매개변수 등 다양한 요소에 따라 달라집니다. 따라서 사용할 범위는 개발자가 결정합니다. 탐색은 메서드에 유효한 범위만 문서화합니다.

요청 및 응답

메서드에 요청 또는 응답 본문이 있으면 각각 request 또는 response 섹션에 기록됩니다. 예를 들어 enable 메서드의 경우 request 섹션의 콘텐츠는 메서드 요청이 ID가 EnableServiceRequest인 JSON 스키마로 정의되었음을 나타냅니다. 이 스키마는 최상위 스키마 섹션에서 찾을 수 있습니다.

매개변수

메서드에 사용자가 지정해야 하는 매개변수가 있으면 이러한 매개변수는 메서드 수준 parameters 섹션에 기록됩니다. 이 섹션에는 매개변수 이름에서 해당 매개변수에 대한 세부정보로의 키/값 매핑이 포함되어 있습니다.

예를 들어 enable 메서드에는 name이라는 매개변수가 하나 있습니다. 매개변수는 path 또는 URL query에 포함될 수 있습니다. location 속성은 클라이언트 라이브러리가 매개변수를 배치해야 하는 위치를 나타냅니다.

매개변수 데이터 type(강력한 타이핑 언어에 유용), 매개변수가 required인지 여부, 매개변수가 열거형인지 여부 등 매개변수를 설명하는 다른 속성도 많이 있습니다. 이러한 속성에 대한 자세한 내용은 이 API의 참고 문서를 확인하세요.

매개변수 순서

클라이언트 라이브러리는 여러 가지 방법으로 인터페이스를 구조화할 수 있습니다. 한 가지 방법은 메서드 서명에 API 매개변수별로 하나의 메서드를 포함하는 것입니다. 하지만 JSON은 순서가 지정되지 않은 형식이므로 메서드 서명에서 매개변수의 순서 지정 방법을 프로그래매틱 방식으로 알기 어렵습니다. parameterOrder 배열은 요청을 위한 고정 매개변수의 순서를 지정합니다. 배열은 각 매개변수의 이름을 중요도 순으로 나열합니다. 경로 또는 쿼리 매개변수를 포함할 수 있지만 배열의 모든 매개변수는 필수 항목입니다.

미디어 업로드

메서드가 이미지, 오디오, 동영상과 같은 미디어 업로드를 지원하는 경우 해당 미디어의 업로드를 지원하는 위치와 프로토콜은 mediaUpload 섹션에 설명되어 있습니다. 이 섹션에는 지원되는 업로드 프로토콜과 업로드할 수 있는 미디어 종류에 대한 세부정보가 포함됩니다.

enable 메서드에는 mediaUpload 섹션이 포함되지 않습니다. 그러나 일반적인 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 속성은 메서드가 미디어 업로드를 지원하는지 여부를 결정하는 불리언 값입니다. 값이 true이면 mediaUpload 섹션에 업로드 가능한 미디어 종류가 설명됩니다.

accept 속성은 업로드가 허용되는 mime 유형을 결정하는 미디어 범위 목록입니다. 위의 예에 표시된 엔드포인트는 모든 이미지 형식을 허용합니다.

maxSize 속성에는 최대 업로드 크기가 포함됩니다. 값은 MB, GB, TB 단위의 문자열입니다. 위의 예에서 업로드 크기는 최대 10MB로 제한됩니다. 이 값은 해당 API에 대한 개별 사용자의 남은 저장용량 할당량을 반영하지 않으므로 업로드가 maxSize보다 작더라도 클라이언트 라이브러리는 공간 부족으로 인해 실패한 업로드를 처리할 준비가 되어 있어야 합니다.

protocols 섹션에는 메서드가 지원하는 업로드 프로토콜이 나열됩니다. simple 프로토콜은 단순히 단일 HTTP 요청으로 지정된 엔드포인트로 미디어를 게시합니다. resumable 프로토콜은 path URI에 지정된 엔드포인트가 재개 가능한 업로드 프로토콜을 지원함을 암시합니다. multipart 속성이 true이면 엔드포인트는 멀티파트 업로드를 허용합니다. 즉, JSON 요청과 미디어를 멀티파트/관련 본문에 함께 래핑하고 함께 전송할 수 있습니다. simple 및 resumable 프로토콜 모두 다중 파트 업로드를 지원할 수 있습니다.

path 속성은 URI 템플릿이며 요청 작성 섹션에 설명된 것처럼 메서드의 path 속성과 같이 확장됩니다.

미디어 다운로드

메서드가 이미지, 오디오, 동영상과 같은 미디어 다운로드를 지원하는 경우 supportsMediaDownload 매개변수로 표시됩니다.

"supportsMediaDownload": true,

미디어를 다운로드할 때는 alt 쿼리 매개변수를 요청 URL의 media로 설정해야 합니다.

API 메서드의 useMediaDownloadService 속성이 true이면 servicePath 앞에 /download을 삽입해 리디렉션을 방지합니다. 예를 들어 servicePath와 path의 연결이 /youtube/v3/captions/{id}이면 다운로드 경로는 /download/youtube/v3/captions/{id}가 됩니다. useMediaDownloadService가 false인 경우에도 /download로 미디어 다운로드 URL을 작성하는 것이 좋습니다.

참고: 하나의 API 메서드가 미디어 다운로드와 미디어 업로드를 모두 지원할 수 있습니다. 미디어 업로드와 미디어 다운로드의 요청 URL 구성 로직은 독립적으로 작동하며 서로 간섭하지 않습니다. 따라서 이러한 API 메서드에는 미디어 다운로드를 위한 하나의 /download/... URL과 미디어 업로드를 위한 하나의 /upload/... URL이 포함됩니다. 하지만 단일 요청으로 미디어 업로드와 미디어 다운로드를 수행할 수는 없습니다.

공통 매개변수

최상위 탐색 문서에는 parameters 속성이 포함되어 있습니다. 이 섹션은 각 메서드의 매개변수 섹션과 비슷하지만, 이러한 매개변수는 API의 모든 메서드에 적용할 수 있습니다.

예를 들어 Service Usage API의 get 및 list 메서드는 요청 매개변수에 prettyPrint 매개변수를 포함할 수 있으며, 이는 모든 메서드에 대한 응답을 인간이 읽을 수 있는 형식으로 지정합니다. 다음은 공통 매개변수 목록입니다.

매개변수	의미	참고	적용 범위
`access_token`	현재 사용자의 OAuth 2.0 토큰입니다.	OAuth 2.0 토큰을 제공하는 한 가지 방법입니다.
`alt`	응답의 데이터 형식입니다.	유효한 값: `json`, `atom`, `csv`. 기본값: API에 따라 다릅니다. 일부 값은 API에 사용할 수 없습니다.	모든 리소스에 대한 모든 작업에 적용됩니다.
`callback`	콜백 함수입니다.	응답을 처리하는 자바스크립트 콜백 함수의 이름입니다. JavaScript JSON-P 요청에서 사용됩니다.
`fields`	응답에 포함할 필드의 하위 집합을 지정하는 선택기입니다.	성능 개선을 위해 사용합니다.
`key`	API 키입니다. (필수)	OAuth 2.0 토큰을 제공하지 않는 한 필수 항목입니다. API 키는 프로젝트를 식별하고 사용자에게 API 액세스 권한, 할당량, 보고서를 제공합니다. API 콘솔에서 프로젝트의 API 키를 가져옵니다.
`prettyPrint`	들여쓰기와 줄바꿈이 적용된 응답을 반환합니다.	`true`인 경우 인간이 읽을 수 있는 형식으로 응답을 반환합니다. 기본값: API에 따라 다릅니다. `false`인 경우 응답의 페이로드 크기가 줄어 일부 환경에서 성능이 개선될 수 있습니다.
`quotaUser`	`userIp`의 대체 매개변수입니다.	사용자의 IP 주소를 모르더라도 서버 측 애플리케이션에서 사용자별 할당량을 적용할 수 있습니다. 예를 들어 사용자를 대신하여 App Engine에서 크론 작업을 실행하는 애플리케이션이 여기에 해당합니다. 사용자를 고유하게 식별하는 임의의 문자열을 선택할 수 있지만 길이는 40자로 제한됩니다. 두 매개변수가 모두 제공되면 `userIp`는 무시됩니다. 사용 한도 지정에 대해 자세히 알아보세요.
`userIp`	API 호출을 실행하는 최종 사용자의 IP 주소입니다.	서버 측 애플리케이션에서 API를 호출하는 경우 사용자별 할당량을 적용할 수 있습니다. 사용 한도 지정에 대해 자세히 알아보세요.

인라인 문서

각 탐색 문서는 API에 대한 인라인 문서를 제공하는 여러 description 필드로 주석 처리됩니다. 다음 API 요소에 대한 description 필드를 찾을 수 있습니다.

API 자체
OAuth 범위
리소스 스키마
API 메서드
메서드 매개변수
특정 매개변수에 허용되는 값

이러한 필드는 Google API 탐색 서비스를 사용하여 인간이 읽을 수 있는 클라이언트 라이브러리 문서(예: JavaDoc)를 생성하려는 경우에 특히 유용합니다.

Discovery API 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.