APIコールを実施する

アプリケーションの登録後は、APIコールを実施してください。Yahoo!広告 APIに実際にリクエストして、正常なレスポンスが返ってくるかを確認できます。

APIコールで利用するエンドポイントは、以下のとおりです。

種別 URI
認可API https://biz-oauth.yahoo.co.jp/oauth
検索広告 API https://ads-search.yahooapis.jp/api
ディスプレイ広告 API https://ads-display.yahooapis.jp/api

また、アプリケーション登録時に取得した項目、およびAPIコールの手順中で取得する項目をパラメータに設定する必要があります。
各パラメータの詳細は、以下のとおりです。

パラメータ名 内容
client_id 登録済みアプリケーションのクライアントID。サンプル内で「CLIENT_ID」と書かれた部分に入力します。
client_secret 登録済みアプリケーションのクライアントシークレット。サンプル内で「CLIENT_SECRET」と書かれた部分に入力します。
redirect_uri アプリケーション登録時に入力したリダイレクトURI。サンプル内で「REDIRECT_URI」と書かれた部分に入力します。
リダイレクトURIには、半角英数字と以下の半角記号を利用できます。
! # % & + - . / : ; = ? @ _ ~ 
code APIコールの手順中で取得する認可コード。サンプル内で「AUTH_CODE」と書かれた部分に入力します。
access_token APIコールの手順中で取得するアクセストークン。サンプル内で「ACCESS_TOKEN」と書かれた部分に入力します。
refresh_token APIコールの手順中で取得するリフレッシュトークン。サンプル内で「REFRESH_TOKEN」と書かれた部分に入力します。
state 認可リクエストの送信時に設定できるパラメータ。他者に判別されにくい、ユニークかつランダムな文字列(最大512文字)を設定します。
stateパラメータには、半角英数字と以下の半角記号を利用できます。
! # % & + - . / : ; = ? @ _ ~ 

手順は以下のとおりです。

1. アプリケーション利用者の認可を得るため、認可画面へのリダイレクトを実施します。
エンドポイント(認可API)のパラメータに、クライアントIDとリダイレクトURIを設定します。
また、セキュリティ対策として、リクエストの送信時にstateパラメータの指定を推奨します。リクエストごとにユニークかつランダムな文字列をstateパラメータに指定することで、認可リクエストと認可サーバーからのレスポンスの通信を一意に特定できます。 stateパラメータに使用できる値は「RFC6749 Appendix A.5.」(外部サイト)を参照してください。

https://biz-oauth.yahoo.co.jp/oauth/v1/authorize?response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&scope=yahooads
&state=THIS_VALUE_SHOULD_BE_UNIQUE_PER_REQUEST

2. 認可画面が表示されるので、アプリケーション利用者は「承認」をクリックします。


3. アプリケーション利用者が承認した場合、エンドポイントに設定したリダイレクトURIへリダイレクトされ、認可コード(code)が渡されます。
なお、認可コードは10分経過すると無効化されます。その際は再取得してください。
また、手順1. でstateパラメータを指定した場合は、指定したstateの値と、リダイレクトレスポンスのURIに含まれるstateクエリパラメータの値が同一であるかを検証してください。

4. 認可コードを使って、認可APIへリクエストを送信します。
パラメータにクライアントID、クライアントシークレット、リダイレクトURI、手順3. で取得した認可コードを設定します。

https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=authorization_code
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&redirect_uri=REDIRECT_URI
&code=AUTH_CODE

5. アクセストークン と リフレッシュトークンがレスポンスされます。
アクセストークンはレスポンスから1時間を経過すると無効化されます。

{"access_token":"ACCESS_TOKEN",
"expires_in":"3600",
"token_type":"Bearer",
"refresh_token":"REFRESH_TOKEN"}

6. 取得したアクセストークンをHTTPヘッダーに含めて、Yahoo!広告 APIにAPIコールを実施します。
HTTPステータスコードに200がレスポンスされれば成功です。

Authorization: Bearer "ACCESS_TOKEN"

Yahoo! 広告APIではOpenAPIでのインターフェースを公開しています。
 ・検索広告 API
 ・ディスプレイ広告 API
OpenAPIについては、以下をご参照ください。
 OpenAPI

【アクセストークンの再取得】
アクセストークンが失効した場合は、リフレッシュトークンを使って再取得してください。
リフレッシュトークンは、ユーザーが当該アプリケーションの承認を解除するまで有効です。

https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=refresh_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&refresh_token=REFRESH_TOKEN

アクセストークンがレスポンスされます。

{"access_token":"ACCESS_TOKEN",
"expires_in":3600,
"token_type":"Bearer"}

【トークンの無効化(revoke)】
取得済みのアクセストークンやリフレッシュトークンを個別に指定して無効化できます。アプリケーションユーザーの認可を取り消す場合などにご利用ください。
トークン無効化 URLに HTTP POST リクエストすることによって、特定のトークンを無効化できます。アクセストークンおよびリフレッシュトークンは、"application/x-www-form-urlencoded"形式を使ったtokenパラメータで指定します。
以下は curl コマンドを使った例です。
※各行末の「\」は、半角バックスラッシュ(\の半角版)に置換えてください。

curl https://biz-oauth.yahoo.co.jp/oauth/v1/revoke \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "token=TOKEN"

リクエストに成功すると、HTTP ステータスコード 200 がレスポンスされます。