このページは Cloud Translation API によって翻訳されました。

API の使用

はじめに

このドキュメントは、Google API とやり取りするクライアントライブラリ、IDE プラグインなどのツールを作成するデベロッパーを対象としています。Google API Discovery Service では、上記の API のすべてを、シンプルな API を通じて、他の Google API に関する機械が読み取り可能なメタデータとして公開することができます。このガイドでは、Discovery ドキュメントの各セクションの概要と、ドキュメントの使い方に関するヒントを紹介しています。

API の呼び出しはすべて、SSL を使用する未認証の JSON ベースの REST リクエストです。つまり、URL は https で始まります。

Google API Discovery Service のコンセプトになじみがない場合は、コーディングを開始する前にスタートガイドをお読みください。

ディスカバリドキュメントの形式

このセクションでは、Discovery ドキュメントの概要を説明します。

以下の例はすべて、Google Cloud Service Management API のディスカバリドキュメントを使用しています。Google Cloud Service Management API のディスカバリドキュメントを読み込むには、次の GET リクエストを実行します。

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 Discovery Service は API にアクセスする RESTful メソッドのみをサポートしているため、protocol は常に rest の固定値になります。

servicePath フィールドは、この API バージョンのパス接頭辞を示します。

認証

auth セクションには、API の OAuth 2.0 認証スコープの詳細が含まれています。OAuth 2.0 でスコープを使用する方法について詳しくは、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。

auth セクションには、oauth2 セクションと scopes セクションがネストされています。scopes セクションは、スコープ値からスコープの詳細への Key-Value マッピングです。

"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 の 3 つのサブリソースがあります。

"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 の 3 つのメソッドがあります。

スキーマは、API 内のリソースの状態を示します。各ディスカバリドキュメントには最上位の schemas セクションがあり、このセクションにはオブジェクトに対するスキーマ ID の名前と値のペアが含まれています。スキーマ ID は API ごとに一意であり、ディスカバリドキュメントの methods セクションでスキーマを一意に識別するために使用されます。

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

API Discovery Service は、スキーマ表現に JSON スキーマドラフト 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 スキーマ仕様のものです）。

また、メソッドがリクエスト本文とレスポンス本文を示す際にスキーマを参照することもできます。詳しくは、メソッドのセクションをご覧ください。

Methods

ディスカバリドキュメントの中核はメソッドを中心に構築されています。メソッドとは、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 セクションは、メソッド名からそのメソッドに関するその他の詳細への Key-Value のマップです。次の例では、get、list、create の 3 つのメソッドを文書化しています。

"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 でサポートされているすべてのスコープに関する情報が含まれています。メソッドがこれらのスコープのいずれかをサポートする場合、スコープ配列が含まれます。この配列には、メソッドがサポートしているスコープごとに 1 つのエントリがあります。たとえば、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"
]

アプリケーションで使用する認証スコープの選択は、呼び出されているメソッドや、メソッドとともに送信されるパラメータなど、さまざまな要因によって変わることに注意してください。したがって、使用するスコープを決定するのはデベロッパーです。Discovery では、メソッドに有効なスコープのみが文書化されます。

リクエストとレスポンス

メソッドにリクエスト本文またはレスポンス本文がある場合は、それぞれ request セクションまたは response セクションに記載されます。上記の get の例では、メソッドに response 本文があります。

"response": {
  "$ref": "Rollout"
}

上記の構文は、レスポンスの本文が ID が Rollout の JSON スキーマによって定義されていることを示しています。このスキーマは、最上位のスキーマのセクションにあります。リクエスト本文とレスポンスの本文では、スキーマの参照に $ref 構文が使用されます。

パラメータ

メソッドにユーザーが指定する必要のあるパラメータがある場合、それらのパラメータはメソッドレベルの parameters セクションに記載されます。このセクションでは、パラメータ名の Key-Value マッピングと、そのパラメータの詳細を示します。

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

上記の例では、get メソッドに serviceName と rolloutId の 2 つのパラメータがあります。パラメータは path または URL query に指定できます。location プロパティは、クライアントライブラリがパラメータを配置する場所を示します。

パラメータを記述しているプロパティは他にも数多くあります。たとえば、パラメータデータ type（厳密に型指定された言語に役立ちます）、パラメータが required かどうか、パラメータが列挙型かどうかなどです。プロパティについて詳しくは、リファレンスガイドをご覧ください。

パラメータの順序

クライアントライブラリがインターフェースを構造化するにはさまざまな方法があります。1 つの方法は、メソッドシグネチャに各 API パラメータを含むメソッドを指定することです。ただし、JSON は順序付けされていない形式であるため、メソッドシグネチャのパラメータの順序をプログラムで認識するのは困難です。parameterOrder 配列は、リクエストを行うための固定パラメータ順序設定を提供します。配列には、各パラメータの名前が重要度の高い順に表示されます。パスやクエリパラメータを含めることができますが、配列内のすべてのパラメータが必要です。上記の例では、Java メソッドのシグネチャは次のようになります。

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 プロパティは、メソッドがメディアのアップロードをサポートしているかどうかを指定するブール値です。値が true の場合、mediaUpload セクションにはアップロード可能なメディアの種類が記載されます。

accept プロパティは、アップロード可能な MIME タイプを決定する media-ranges のリストです。上記の例に示されているエンドポイントは、任意の画像形式を受け入れます。

maxSize プロパティは、アップロードの最大サイズです。値は MB、GB、TB 単位の文字列です。上記の例では、アップロードの上限が 10 MB に制限されています。この値は、個々のユーザーのその API の残りのストレージ割り当てを反映するものではありません。そのため、アップロードが maxSize 未満であっても、容量不足のためにアップロードが失敗したときは、クライアントライブラリで処理できる準備が必要です。

protocols セクションには、メソッドがサポートするアップロードプロトコルが一覧表示されます。simple プロトコルは、単一の HTTP リクエストでメディアを指定されたエンドポイントに投稿するだけです。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 を作成することをおすすめします。

一般的なパラメータ

最上位の Discovery ドキュメントには parameters プロパティが含まれています。このセクションは各メソッドのパラメータセクションと同様ですが、API のどのメソッドにもこれらのパラメータを適用できます。

たとえば、Google Cloud Service Management API の get、insert、list メソッドのリクエストパラメータには、prettyPrint パラメータを含めることができます。これにより、すべてのメソッドのレスポンスが、人が読める形式でフォーマットされます。一般的なパラメータのリストは次のとおりです。

パラメータ	意味	備考	適用性
`access_token`	現在のユーザーの OAuth 2.0 トークン。	OAuth 2.0 トークンを提供する方法の一例。
`alt`	応答のデータ形式	有効な値: `json`、`atom`、`csv` デフォルト値: API によって異なります。 API によっては使用できない値もあります。	すべてのリソースに対するすべてのオペレーションに適用されます。
`callback`	コールバック関数。	レスポンスを処理する JavaScript コールバック関数の名前。 JavaScript JSON-P リクエストで使用されます。
`fields`	レスポンスに含めるフィールドのサブセットを指定するセレクタ。	詳細については、部分レスポンスのドキュメントをご覧ください。パフォーマンスを向上させるために使用します。
`key`	API キー（必須*）	*OAuth 2.0 トークンを指定しない場合は必須。 API キーによりプロジェクトが特定され、API アクセス、割り当て、レポートが提供されます。 API コンソールからプロジェクトの API キーを取得します。
`prettyPrint`	ID と改行を含むレスポンスを返します。	`true` の場合は、人が読める形式でレスポンスを返します。デフォルト値: API によって異なります。 `false` の場合、環境によっては、レスポンスのペイロードサイズを減らすことで、パフォーマンスが向上する場合があります。
`quotaUser`	`userIp` の代替。	ユーザーの IP アドレスが不明な場合でも、サーバー側アプリケーションからユーザーごとの割り当てを適用できます。この状況は、ユーザーに代わって App Engine で cron ジョブを実行するアプリケーションで発生する場合があります。ユーザーを一意に識別する任意の文字列を 40 文字以内で選択できます。両方が指定されている場合、`userIp` が優先されます。詳細については、キャップの使用法をご覧ください。
`userIp`	API 呼び出しが行われているエンドユーザーの IP アドレス。	サーバー側アプリケーションから API を呼び出す際に、ユーザーごとの割り当てを適用できます。詳細については、キャップの使用法をご覧ください。

機能

場合によっては、API が Discovery ドキュメントの他の範囲に含まれないカスタム機能をサポートする場合もあります。これらは features 配列に収集されます。特徴配列には、API でサポートされている特別な特徴ごとに文字列ラベルが含まれます。現時点では、サポートされている機能は dataWrapper のみですが、今後、その他の機能がサポートされる可能性があります。

"features": dataWrapper

dataWrapper 機能は、API に対するリクエストとレスポンスがすべて data JSON オブジェクトにラップされることを示します。これは古い Google API の機能ですが、今後非推奨となります。モデレーター v1 と翻訳 v2 の API が dataWrapper 機能をサポートしています。

API が「dataWrapper」機能をサポートしている場合、クライアントライブラリのデベロッパーは次の操作を行う必要があります。

リクエストの場合: リクエストリソースを data JSON オブジェクトでラップします。
レスポンスの場合: data JSON オブジェクト内のリソースを見つけます。

ディスカバリドキュメント内のスキーマにはデータラッパーが含まれていないため、これらを明示的に追加または削除する必要があります。たとえば、次のように、「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 Discovery Service を使用して、クライアントライブラリ（JavaDoc など）の人が読める形式のドキュメントを生成する場合に特に便利です。

次のステップ

クライアントライブラリの構築