アクセス トークンと更新トークンを取得する

ユーザーが Microsoft Advertising アカウントを管理するための同意を付与したら、アクセス トークンの承認 code を引き換えることができます。

1. ユーザーが同意を与えた後に返された をcode引き換えることによって、アクセス トークンを要求します。 JSON 応答ストリームから access_token、 refresh_token、 expires_in の値を取得します。
2. アクセス トークンを受け取ったとき、 expires_in の値は、アクセス トークンの有効期限が切れるまでの最大時間 (秒単位) を表します。 アクセス トークンの有効期限が切れる前、または API アクセスが必要になる前に、 アクセス トークンを更新する必要があります。
3. を正常に取得 access_tokenしたら、要求で トークンを 使用 して広告 API をBingできます。 例については、 最初の API 呼び出し ガイドを参照してください。

上記の手順 1 と 2 の例を次に示します。

# Replace your_client_id with your registered application ID. 
$clientId = "your_client_id"

Start-Process "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=$clientId&scope=openid%20profile%20https://ads.microsoft.com/msads.manage%20offline_access&response_type=code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient&state=ClientStateGoesHere&prompt=login"

$code = Read-Host "Grant consent in the browser, and then enter the response URI here:"
$code = $code -match 'code=(.*)\&'
$code = $Matches[1]

# Get the initial access and refresh tokens. 

$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=authorization_code&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient"

$oauthTokens = ($response.Content | ConvertFrom-Json)  
Write-Output "Access token: " $oauthTokens.access_token  
Write-Output "Access token expires in: " $oauthTokens.expires_in  
Write-Output "Refresh token: " $oauthTokens.refresh_token 

# The access token will expire e.g., after one hour. 
# Use the refresh token to get new access and refresh tokens. 

$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=refresh_token&refresh_token=$($oauthTokens.refresh_token)"

$oauthTokens = ($response.Content | ConvertFrom-Json)  
Write-Output "Access token: " $oauthTokens.access_token  
Write-Output "Access token expires in: " $oauthTokens.expires_in  
Write-Output "Refresh token: " $oauthTokens.refresh_token

アクセス トークン要求の詳細

を目的のaccess_tokenリソースに引き換codeえることができます。 これを行うには、エンドポイントに要求をPOST/token送信します。

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only applicable for web apps

要求の本文には要求パラメーターを含める必要があり、Content-Type ヘッダーは application/x-www-form-urlencoded に設定する必要があります。 前の手順で取得した承認コードの値に code パラメーターを設定し、許可の種類を authorization_code に設定します。 redirect_uriは、承認コードを取得するために使用されるリダイレクト URI と完全に一致している必要があります。 リダイレクト URL は必ずエンコードしてください。 Web アプリケーションを登録した場合は、 client_secret パラメーターを含め、「 アプリケーションの登録」でプロビジョニングされた値に設定します。

次の表には、Bing Ads API クライアントが初期アクセス トークンの要求に含めることができるパラメーターが含まれています。 省略可能なパラメーターの詳細については、Microsoft ID プラットフォーム OAuth 2.0 承認コード フローのドキュメントを参照してください。

トークン要求の詳細を更新する

アクセス トークンは有効期間が短く、リソースへのアクセスを続行するには有効期限が切れた後に更新する必要があります。 これを行うには、エンドポイントに別POSTの/token要求を送信し、今度は ではなく をrefresh_tokencode指定します。 更新トークンは、クライアントが既に同意を受けているすべてのアクセス許可に対して有効です。

更新トークンには有効期間が指定されていません。 通常、更新トークンの有効期間は比較的長いです。 ただし、場合によっては、更新トークンの有効期限が切れたり、取り消されたり、目的のアクションに対して十分な特権が不足したりする場合があります。 アプリケーションは、トークン発行エンドポイントから返されたエラーを正しく予期して処理する必要があります。 OAuth エラーの詳細については、「 一般的な OAuth エラー 」と「 認証と承認のエラー コード」を参照してください。

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only applicable for web apps

要求の本文には要求パラメーターを含める必要があり、Content-Type ヘッダーは application/x-www-form-urlencoded に設定する必要があります。 更新トークン パラメーターを、前の手順で取得した更新トークンの値に設定し、許可の種類を refresh_token に設定します。 Web アプリケーションを登録した場合は、 client_secret パラメーターを含め、「 アプリケーションの登録」でプロビジョニングされた値に設定します。

次の表には、Bing Ads API クライアントがアクセス トークンを更新するための要求に含めることができるパラメーターが含まれています。 省略可能なパラメーターの詳細については、Microsoft ID プラットフォーム OAuth 2.0 承認コード フローのドキュメントを参照してください。

更新トークンは、新しいアクセス トークンの取得に使用しても取り消されませんが、古い更新トークンを破棄する必要があります。 OAuth 2.0 仕様には、「承認サーバーが新しい更新トークンを発行する場合があります。その場合、クライアントは古い更新トークンを破棄し、それを新しい更新トークンに置き換える必要があります。 承認サーバーは、新しい更新トークンをクライアントに発行した後、古い更新トークンを取り消すことができます。

更新トークンは、常にアプリケーションに対して完全に不透明になります。 パブリック クライアントの場合は 90 日間など、有効期間が長くなりますが、更新トークンが一定期間続くと想定するようにアプリを記述しないでください。 更新トークンはいつでも無効にすることができます。また、更新トークンが有効かどうかをアプリが認識する唯一の方法は、トークン要求を行ってトークンを引き換えようとすることです。 最新の更新トークンを使用して同じデバイス上のトークンを継続的に更新する場合でも、Microsoft Advertising ユーザーがパスワードを変更した場合、信頼されたデバイスの一覧からデバイスを削除した場合、またはアプリケーションが代わりに認証するためのアクセス許可を削除した場合など、ユーザーの 同意を要求 する必要があります。 Microsoft は、事前の警告なしにいつでも、ユーザーの同意を再び付与する必要があると判断する場合があります。 その場合、次の例に示すように、承認サービスから無効な許可エラーが返されます。

{"error":"invalid_grant","error_description":"The user could not be authenticated or the grant is expired. The user must first sign in and if needed grant the client application access to the requested scope."}

パブリック更新トークンは、付与されたデバイスにのみバインドされることに注意してください。 たとえば、ネイティブ アプリを登録し、リダイレクト URI として使用 https://login.microsoftonline.com/common/oauth2/nativeclient する場合、同じデバイスでのみ更新できることを保証します。 Microsoft Azure などのリージョンやデバイスにまたがるサービスでアプリを実行しているクライアントは、Web アプリをクライアント シークレットに登録する必要があります。 リダイレクト URI は localhost にできますが、 に https://login.microsoftonline.com/common/oauth2/nativeclientすることはできません。 クライアント シークレットで を使用 https://login.microsoftonline.com/common/oauth2/nativeclient すると、次のエラーが返されます。

{"error":"invalid_request","error_description":"Public clients can't send a client secret."} Likewise for Web apps please note that refresh tokens can be invalidated at any moment.

クライアント シークレットなしでプロビジョニングされた更新トークンを使用して新しいアクセストークンと更新トークンを要求しようとすると、同じエラーが発生します。

OAuth エラーの詳細については、「 一般的な OAuth エラー 」と「 認証と承認のエラー コード」を参照してください。

次の手順

関連項目

概要