このページの一部またはすべての情報は、S3NS の Trusted Cloud に適用されない場合があります。

Discovery API を使用する

このドキュメントは、Google API とやり取りするためのクライアントライブラリ、IDE プラグイン、その他のツールを作成するデベロッパーを対象としています。Google APIs Discovery Service を使用すると、シンプルな API を介して他の Google API に関する機械可読のメタデータを公開することで、前述のような作業をすべて行うことができます。このガイドでは、ディスカバリドキュメントの各セクションの概要と、ドキュメントの使用方法に関するヒントについて説明します。

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

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

このセクションでは、ディスカバリドキュメントの概要について説明します。

以下のすべての例では、Service Usage API のディスカバリドキュメントを使用しています。Service Usage API のディスカバリドキュメントは、次の GET リクエストを実行することで読み込むことができます。

GET https://serviceusage.s3nsapis.fr/$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.s3nsapis.fr/",
"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.s3nsapis.fr/",
"protocol": "rest"

これらの API レベルのプロパティには、API の特定のバージョンに関する詳細（name、version、title、description など）が含まれます。APIs 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": {
        "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
  }
}

各 resource セクションには、リソースに関連付けられているメソッドが含まれています。たとえば、Service Usage API には、services リソースに関連する 6 つのメソッド（get、enable、disable、batchGet、batchEnable、list）があります。

スキーマは、API 内のリソースがどのようなものかを示します。各ディスカバリドキュメントには最上位の schemas セクションがあり、そこにはスキーマ ID と、オブジェクトの名前と値のペアが含まれています。スキーマ 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
  }
}

APIs Discovery Service は、スキーマ表現に JSON スキーマ draft-03 を使用します。EnableServiceResponse リソースの JSON スキーマのスニペットと、参照する GoogleApiServiceusagev1Service を以下に示します。これらのスキーマの横には、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 プロパティは Service Usage API の Discovery ドキュメントにある別のスキーマ（ID GoogleApiServiceusageV1Service のスキーマ）への参照です。EnableServiceResponse リソースの GoogleApiServiceusageV1Service プロパティは、GoogleApiServiceusageV1Service スキーマの値で置き換えることができます（$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 セクションは、メソッド名からそのメソッドに関する詳細情報への Key-Value マップです。以下の例では、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 でサポートされているすべてのスコープに関する情報が記述されています。メソッドがこれらのスコープのいずれかをサポートする場合、スコープ配列が存在します。この配列には、メソッドでサポートされているスコープごとに 1 つのエントリがあります。

アプリケーションで使用する認証スコープの選択は、呼び出されるメソッドや、メソッドと一緒に送信されるパラメータなど、さまざまな要因によって異なります。使用するスコープの決定はデベロッパーが行います。Discovery は、メソッドに有効なスコープのみをドキュメント化します。

リクエストとレスポンス

メソッドにリクエスト本文またはレスポンス本文がある場合は、それぞれ request セクションまたは response セクションに記述します。たとえば、enable メソッドの場合、request セクションの内容は、メソッドのリクエストが ID EnableServiceRequest の JSON スキーマによって定義されることを示しています。このスキーマは最上位の schemas セクションにあります。

パラメータ

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

たとえば、enable メソッドには name というパラメータが 1 つあります。パラメータは 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 単位の文字列です。上記の例では、アップロードの最大サイズが 10 MB に制限されています。この値は、該当の API に対する個々のユーザーの保存容量の残りを反映するものではありません。アップロードが maxSize より少ない場合でも、クライアントライブラリがアップロードの失敗時に対処できるよう準備しておく必要があります。

protocols セクションには、メソッドがサポートするアップロードプロトコルを記述します。simple プロトコルは、単一の HTTP リクエストで指定されたエンドポイントにメディアを POST するだけです。resumable プロトコルは、path URI で指定されたエンドポイントが再開可能なアップロードプロトコルをサポートしていることを意味します。multipart プロパティが true の場合、エンドポイントはマルチパートアップロードを受け入れます。つまり、JSON リクエストとメディアの両方を 1 つの mutlipart/related 本文にラップできます。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 を作成することをおすすめします。

注: 1 つの API メソッドでメディアのダウンロードとアップロードの両方をサポートできます。メディアのアップロードとダウンロードの URL 構築ロジックは独立して機能し、相互に干渉しません。その結果、このような API メソッドには、メディアのダウンロード用に /download/... URL が 1 つ、メディアのアップロード用に /upload/... URL が 1 つ含まれます。ただし、1 回のリクエストでメディアのアップロードとダウンロードを行うことはできません。

共通パラメータ

最上位のディスカバリドキュメントには parameters プロパティが含まれています。このセクションは、各メソッドのパラメータセクションに似ていますが、これらのパラメータは API 内の任意のメソッドに適用できます。

たとえば、Service Usage API の get メソッドや 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 キーは APIs Console から取得します。
`prettyPrint`	インデントと改行の付いたレスポンスを返します。	`true` の場合は、人が読める形式でレスポンスを返します。デフォルト値: API ごとに異なる `false` の場合、環境によっては、レスポンスのペイロードサイズを減らすことで、パフォーマンスが向上する場合があります。
`quotaUser`	`userIp` の代替。	ユーザーの IP アドレスが不明な場合でも、サーバーサイドアプリケーションからユーザーごとの割り当てを適用できます。この状況は、ユーザーに代わって App Engine で cron ジョブを実行するアプリケーションで発生する場合があります。ユーザーを一意に識別する任意の文字列を 40 文字以内で選択できます。両方が指定されている場合、`userIp` が優先されます。詳細については、キャップの使用法をご覧ください。
`userIp`	API 呼び出しが行われているエンドユーザーの IP アドレス。	サーバーサイドアプリケーションから API を呼び出す際に、ユーザーごとの割り当てを適用できます。詳細については、キャップの使用法をご覧ください。

インラインドキュメント

各ディスカバリドキュメントには、API のインラインドキュメントを提供する多くの description フィールドが含まれています。description フィールドは、次の API 要素で確認できます。

API 自体
OAuth スコープ
リソーススキーマ
API メソッド
メソッドのパラメータ
特定のパラメータの許容値

これらのフィールドは、Google APIs Discovery Service を使用して、クライアントライブラリ（JavaDoc など）のドキュメントを人が読める形式で生成する場合に特に便利です。