導入の際は、クライアント ライブラリとサンプルの使用をおすすめします。ただし、API との統合にあたって特別なご要望(サポートされていない言語を使用するなど)がある場合には、以下のように、直接リクエストを実行することができます。
目次
呼び出しスタイル
REST は、データのリクエストと変更を一貫した方法で簡単に行うことができるソフトウェア アーキテクチャの一様式です。
REST は「Representational State Transfer」の略語です。Google API においては、HTTP 動詞を使用して、Google が保存しているデータを取得および変更することを指します。
RESTful システムでは、リソースはデータストアに保存されています。クライアントはサーバーに対して特定のアクション(リソースの作成、取得、更新、削除など)を実行するようリクエストを送信し、サーバーはそのアクションを実行して、多くの場合、指定されたリソースの表現形式でレスポンスを送信します。
Google の RESTful API では、クライアントは POST
、GET
、PUT
、DELETE
などの HTTP 動詞を使用して処理を指定します。リソースの指定には、次のような形式を持つ、グローバルに一意の URI が使用されます。
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
すべての API リソースは固有の HTTP アクセス可能 URI を持っているため、REST はデータ キャッシュが可能で、ウェブの分散インフラストラクチャを利用するよう最適化されます。
REST の詳細については、次のサードパーティが提供するドキュメントが理解しやすいかもしれません。
- REST 形式でのウェブ サービスの作成はサービス プロバイダ向けに書かれていますが、REST の概要がわかりやすく説明されています。
- HTTP 1.1 のメソッド定義。
GET
、POST
、PUT
、DELETE
の仕様です。
AdSense Management API の REST
AdSense Management API のオペレーションで説明しているように、サポートされているオペレーションは REST の HTTP 動詞に直接マッピングされています。
AdSense Management API の URI フォーマットは次のようになります。
https://www.googleapis.com/adsense/v1.4/resourceID?parameters
ここで、resourceID
は広告クライアント、広告ユニット、URL チャネル、カスタム チャネル、またはレポート コレクションの識別子、parameters
はクエリに適用するパラメータです。
resourceID
パス拡張のフォーマットによって、現在操作しているリソースを識別できます。次に例を示します。
https://www.googleapis.com/adsense/v1.4/adclients https://www.googleapis.com/adsense/v1.4/adclients/adClientId https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits/adUnitId https://www.googleapis.com/adsense/v1.4/adclients/adClientId/urlchannels ...
API でサポートされている各オペレーションのすべての URI が AdSense Management API リファレンス ドキュメントに要約されています。
次の例では、AdSense Management API でどのように機能するかを示しています。
広告クライアントをリストする:
GET https://www.googleapis.com/adsense/v1.4/adclients/
広告クライアント ca-pub-1234567890123456 の広告ユニットをリストする:
GET https://www.googleapis.com/adsense/v1.4/adClients/ca-pub-1234567890123456/adunits
データ フォーマット
JSON(JavaScript Object Notation)は言語に依存しない一般的なデータ フォーマットであり、任意のデータ構造を単純なテキスト形式で表示します。詳細については、json.org をご覧ください。
リクエストの承認
アプリケーションが AdSense Management API に送信するリクエストには承認トークンが含まれている必要があります。そして、このトークンによって Google に対してアプリケーションが識別されます。
承認プロトコルについて
リクエストの承認のために、アプリケーションは OAuth 2.0 を使用する必要があります。これ以外の承認プロトコルはサポートされていません。
OAuth 2.0 を使ったリクエストの承認
AdSense Management API への全リクエストは、認証されたユーザーによって承認される必要があります。
OAuth 2.0 での承認プロセス、すなわち「フロー」の詳細は、作成するアプリケーションの種類により多少異なります。次の一般的なプロセスはすべてのアプリケーション タイプに該当します。
- 作成するアプリケーションを、Google Developers Console を使用して登録します。Google から後で必要な情報(クライアント ID やクライアント シークレットなど)が提供されます。
- Google Developers Console で AdSense Management API を有効にします(API がコンソールに表示されない場合は、このステップを省略します)。
- アプリケーションは、ユーザーデータにアクセスする必要がある場合、アクセスの範囲を指定して Google にリクエストします。
- 同意画面がユーザーに表示され、アプリケーションによる一部のデータのリクエストを承認するかどうかの確認が行われます。
- ユーザーが承認した場合、短期間有効なアクセス トークンがアプリケーションに付与されます。
- アプリケーションは、アクセス トークンをリクエストに付加してユーザーデータをリクエストします。
- リクエストとトークンが有効であると判断されると、リクエストされたデータが返されます。
新しいアクセス トークンを取得するために更新トークンを使用するなど、追加のステップが含まれるフローもあります。さまざまなタイプのアプリケーションで使用されるフローの詳細については、Google の OAuth 2.0 のドキュメントをご覧ください。
AdSense Management API の OAuth 2.0 の範囲情報は次のようになります。
範囲 | 意味 |
---|---|
https://www.googleapis.com/auth/adsense | AdSense データに対する読み取り/書き込みアクセス |
https://www.googleapis.com/auth/adsense.readonly | AdSense データに対する読み取り専用アクセス |
OAuth 2.0 を使用してアクセスをリクエストするには、アプリケーションを登録したときに Google が提供した情報(クライアント ID やクライアント シークレットなど)と共に範囲情報が必要です。
ヒント: Google API クライアント ライブラリは、承認プロセスの一部を処理できます。これらのライブラリはさまざまなプログラミング言語で使用可能です。詳細については、ライブラリとサンプルのページをご覧ください。
リクエストの実行
最後のステップは API リクエストの実行です。個々の情報については、リファレンス ドキュメント をご覧ください。