Share via

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

  • [アーティクル]

重要

2022 年 6 月、Bing広告の要件として 多要素認証 を導入しました。 この要件に準拠するには、引き続きコードの変更が必要な場合があります。 Microsoft Advertising は、10 月初旬に技術的な適用チェックを実行しています。

このブログ投稿 では、コンプライアンスを確保するために実行する必要がある手順について説明します。

詳細については、 多要素認証要件 ガイドを参照してください。

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

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

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

注:

以下のyour_client_idを、Azure portalポータルによってアプリが割り当てられたアプリケーション (クライアント) ID アプリの登録置き換えます。

# 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

ヒント

トラブルシューティングのヘルプについては、 一般的な OAuth エラー ガイドを参照してください。

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

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

注:

以下のyour_client_idを、Azure portalポータルによってアプリが割り当てられたアプリケーション (クライアント) ID アプリの登録置き換えます。

// 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 承認コード フローのドキュメントを参照してください。

パラメーター 必須 / オプション 説明
client_id 必須出席者 Azure portal - アプリの登録 ポータルによってアプリが割り当てられたアプリケーション (クライアント) ID。
client_secret Web アプリに必須。 アプリのアプリ登録ポータルで作成したアプリケーション シークレット。 client_secretsをデバイスに確実に格納できないため、ネイティブ アプリでは使用しないでください。 サーバー側でclient_secretを安全に格納できる Web アプリと Web API に必要です。 クライアント シークレットは、送信前に URL でエンコードする必要があります。
code 必須出席者 ユーザーの同意を要求した結果として取得したauthorization_code。
code_verifier 推奨 authorization_codeを取得するために使用されたのと同じcode_verifier。 承認コード許可要求で PKCE が使用された場合は必須です。 詳細については、 PKCE RFC を参照してください。
grant_type 必須 認可コードのフローの authorization_code になる必要があります。
redirect_uri 必須 authorization_code の取得に使用されたものと同じ redirect_uri 値。
scope 必須出席者 スコープのスペースで区切られた一覧。 このレッグで要求されるスコープは、 ユーザーの同意を要求したときに含まれるスコープと同じか、またはスコープのサブセットである必要があります。 この要求で指定されたスコープが複数のリソース サーバーにまたがる場合、Microsoft ID プラットフォーム エンドポイントは、最初のスコープで指定されたリソースのトークンを返します。 スコープの詳細については、 アクセス許可、同意、スコープに関するページを参照してください。
tenant 必須出席者 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 アプリケーションで MSA 個人アカウントと Azure AD の職場または学校アカウントの両方が確実にサポートされるように、Bing Ads API 認証のテナントとして使用 common することをお勧めします。

アプリケーションに別のテナントが必要な場合は、「Microsoft ID プラットフォーム エンドポイント」を参照してください。

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

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

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

注:

以下のyour_client_idを、Azure portalポータルによってアプリが割り当てられたアプリケーション (クライアント) ID アプリの登録置き換えます。

// 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 承認コード フローのドキュメントを参照してください。

パラメーター 必須 / オプション 説明
client_id 必須出席者 Azure portal - アプリの登録 ポータルによってアプリが割り当てられたアプリケーション (クライアント) ID。
client_secret Web アプリに必須。 アプリのアプリ登録ポータルで作成したアプリケーション シークレット。 client_secretsをデバイスに確実に格納できないため、ネイティブ アプリでは使用しないでください。 サーバー側でclient_secretを安全に格納できる Web アプリと Web API に必要です。
grant_type 必須出席者 承認コード フローのこの区間に 対して を に refresh_token 設定する必要があります。
refresh_token 必須 アクセス トークンを要求したときに取得したrefresh_token。
scope 必須 スコープのスペースで区切られた一覧。 このレッグで要求されるスコープは、 ユーザーの同意を要求したときに含まれるスコープと同じか、またはスコープのサブセットである必要があります。 この要求で指定されたスコープが複数のリソース サーバーにまたがる場合、Microsoft ID プラットフォーム エンドポイントは、最初のスコープで指定されたリソースのトークンを返します。 スコープの詳細については、 アクセス許可、同意、スコープに関するページを参照してください。
tenant 必須出席者 要求のパスで {tenant} 値を使用して、アプリケーションにサインインできるユーザーを制御できます。 アプリケーションで MSA 個人アカウントと Azure AD の職場または学校アカウントの両方が確実にサポートされるように、Bing Ads API 認証のテナントとして使用 common することをお勧めします。

アプリケーションに別のテナントが必要な場合は、「Microsoft ID プラットフォーム エンドポイント」を参照してください。

更新トークンは、新しいアクセス トークンの取得に使用しても取り消されませんが、古い更新トークンを破棄する必要があります。 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 エラー 」と「 認証と承認のエラー コード」を参照してください。

次の手順

最初の API 呼び出しを行う

関連項目

概要