Discovery API は、各 API の機械可読形式の「ディスカバリ ドキュメント」を取得するための Google API のリストを提供します。
このドキュメントは、Google のクライアントとやり取りするためのクライアント ライブラリ、IDE プラグイン、その他のツールを作成するデベロッパーを対象としています。
調査サービスの背景
コンセプト
Google API Discovery Service は 2 つの基本コンセプトに基づいて構築されています。
- API ディレクトリ: API Discovery Service でサポートされているすべての API のリスト。各ディレクトリ エントリには、サポートされている API の詳細（名前、機能に関する簡単な説明、ドキュメント リンクなど）が表示されています。1 つの API に複数のディレクトリ エントリを指定できます（サポートされているバージョンごとに 1 つ）。
- ディスカバリ ドキュメント: 特定の API に関する、機械で読み取り可能な説明。ディスカバリ ドキュメントには、特定のバージョンの API に関する記述が記載されています。このドキュメントでは、RESTful HTTP 呼び出しを介して各 API のさまざまなメソッドにアクセスする方法について詳しく説明します。ディスカバリ ドキュメントには、API に関連するデータとメソッドの説明のほか、利用可能な OAuth スコープに関する情報、スキーマ、メソッド、パラメータ、利用可能なパラメータ値の説明が含まれています。
データモデル
リソースとは、一意の識別子を持つ個別のデータ エンティティです。Google API Discovery Service は、上記のコンセプトに基づいて 2 種類のリソースを処理します。
API ディレクトリ リスト: API のリスト
各ディレクトリ エントリには、次の情報を含む API の名前 / バージョンのペアが含まれています。
- 識別と説明の情報: 名前、バージョン、タイトル、説明。
- ドキュメント情報: アイコンとドキュメント リンク。
- ステータス情報: ステータス ラベル、API の優先バージョンかどうかを示すステータス。
- ディスカバリ ドキュメント リンク。この API のディスカバリ ドキュメントの URI（完全な URL として指定します。例: https://servicemanagement.googleapis.com/$discovery/rest?version=v1）。
ディスカバリ ドキュメント リソース: 機械で読み取り可能な、特定の API の説明
API ドキュメントで提供される情報に加え、Discovery ドキュメントには以下の情報も含まれています。
- スキーマ: 各 API でアクセスできるデータを記述する API リソース スキーマのリストです。Google API Discovery Service スキーマは JSON スキーマに基づいています。
- メソッド: API メソッドのリストと各メソッドで使用可能なパラメータ
- OAuth スコープ。この API で使用可能な OAuth スコープのリストを示します。
- スキーマ、メソッド、パラメータ、利用可能なパラメータ値の簡単な説明については、インライン ドキュメントを参照してください。
1 つのディレクトリ コレクションは、1 つの API ディレクトリ リソースの概念的なコンテナと、サポートされている各 API のディスカバリ ドキュメント リソースです。
API ディレクトリ リソースとディスカバリ ドキュメント リソースの詳細については、API の使用とリファレンスのドキュメントをご覧ください。
運用
次の表に示すように、Google API Discovery Service のコレクションとリソースに対して 2 つの異なるメソッドを呼び出すことができます。
| オペレーション | 説明 | REST HTTP マッピング |
|---|---|---|
| list | サポートされているすべての API を一覧表示します。 | ディレクトリ リソース URI に対する GET。 |
通話スタイル
REST
サポートされている Google API Discovery Service のオペレーションは、オペレーションで説明しているように、REST HTTP GET 動詞に直接マッピングされます。
Google API Discovery Service URI の特定の形式:
https://discovery.googleapis.com/discovery/v1/apis?parameters
ここで、api は Discovery Document リソースの識別子、version は API の特定バージョンの識別子、_parameters_ はクエリに適用するパラメータです。詳しくは、リファレンス ドキュメントのクエリ パラメータの概要をご覧ください。
API でサポートされている各オペレーションで使用される URI の一覧については、Google API Discovery Service リファレンス ドキュメントをご覧ください。
Google API Discovery Service での動作の例を、いくつか示します。
Google API Discovery Service でサポートされている API をすべてリストします。
GET https://discovery.googleapis.com/discovery/v1/apis
Google Cloud Service Management API バージョン 1 のディスカバリ ドキュメントを取得します。
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1