取得存取和重新整理令牌
重要事項
在 2022 年 6 月，我們引進了 多重要素驗證 作為 Bing 廣告的需求。 您可能仍然需要變更程序代碼，才能符合這項需求。 Microsoft Advertising 會在 10 月初執行技術強制檢查。
此部落格文章 概述您應該採取以確保合規性的步驟。
如需詳細資訊，請參閱 多重要素驗證需求 指南。
一旦使用者同意您管理其 Microsoft Advertising 帳戶，您就可以兌換存取令牌的授權 code 。
- 藉由在使用者授與同意之後兌換
code傳回的 來要求存取令牌。 從 JSON 回應數據流取得 access_token、 refresh_token和 expires_in 值。 - 當您收到存取令牌時， expires_in 的值代表存取令牌到期之前的最大時間，以秒為單位。 在存取令牌到期之前，或在您再次需要 API 存取之前，您應該 重新整理存取令牌。
- 成功取得
access_token之後，您可以在 Bing 廣告 API 的要求中 使用 令牌。 如需範例，請參閱 建立您的第一個 API 呼叫 指南。
以下是上述步驟 1 和 2 的範例。
注意事項
將以下your_client_id取代為應用程式 (用戶端) 標識碼，Azure 入口網站 - 應用程式註冊 入口網站指派您的應用程式。
# 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 入口網站 - 應用程式註冊 入口網站指派您的應用程式。
// 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。 將程式代碼參數設定為上一個步驟中擷取的授權碼值，並將授與類型設定為 authorization_code。 redirect_uri必須完全符合用來取得授權碼的重新導向 URI。 請務必編碼重新導向 URL。 如果您已註冊 Web 應用程式，請包含 client_secret 參數，並將它設定為註冊 應用程式中布建的值。
下表包含 Bing 廣告 API 用戶端可以在初始存取令牌要求中包含的參數。 如需選擇性參數的其他詳細資訊，請參閱 Microsoft 身分識別平台 OAuth 2.0 授權碼流程檔。
| 參數 | 必要/選用 | 說明 |
|---|---|---|
client_id |
必要 | 應用程式 (用戶端) 識別碼，Azure 入口網站 - 應用程式註冊 入口網站指派您的應用程式。 |
client_secret |
Web 應用程式的必要專案 | 您在應用程式註冊入口網站中為應用程式建立的應用程式秘密。 它不應該用於原生應用程式，因為client_secrets無法可靠地儲存在裝置上。 Web 應用程式和 Web API 必須這麼做，這些應用程式和 Web API 能夠安全地將client_secret儲存在伺服器端。 用戶端密碼必須先進行 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 身分識別平台 端點會針對第一個範圍中指定的資源傳回令牌。 如需範圍的詳細說明，請參閱 許可權、同意和範圍。 |
tenant |
必要 | 要求 {tenant} 路徑中的值可用來控制誰可以登入應用程式。 為了確保您的應用程式同時支援 MSA 個人帳戶和 Azure AD 公司或學校帳戶，建議您使用 common 作為 Bing 廣告 API 驗證的租使用者。如果您的應用程式需要另一個租使用者，請參閱 Microsoft 身分識別平台 端點以取得詳細資訊。 |
重新整理令牌要求詳細數據
存取令牌的存留期很短，您必須在令牌過期后重新整理令牌，才能繼續存取資源。 您可以將另一個 POST 要求提交至 /token 端點，這次提供 refresh_token ，而不是 code。 重新整理令牌適用於用戶端已收到同意的所有許可權。
重新整理令牌沒有指定的存留期。 一般而言，重新整理令牌的存留期相對較長。 不過，在某些情況下，重新整理令牌會過期、撤銷，或缺少足夠許可權來執行所需的動作。 您的應用程式必須預期並正確處理令牌發行端點所傳回的錯誤。 如需 OAuth 錯誤的詳細資訊，請參閱 常見的 OAuth 錯誤 和 驗證和授權錯誤碼。
注意事項
將以下your_client_id取代為應用程式 (用戶端) 標識碼，Azure 入口網站 - 應用程式註冊 入口網站指派您的應用程式。
// 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 廣告 API 用戶端可在重新整理存取權杖的要求中包含的參數。 如需選擇性參數的其他詳細資訊，請參閱 Microsoft 身分識別平台 OAuth 2.0 授權碼流程檔。
| 參數 | 必要/選用 | 說明 |
|---|---|---|
client_id |
必要 | 應用程式 (用戶端) 識別碼，Azure 入口網站 - 應用程式註冊 入口網站指派您的應用程式。 |
client_secret |
Web 應用程式的必要專案 | 您在應用程式註冊入口網站中為應用程式建立的應用程式秘密。 它不應該用於原生應用程式，因為client_secrets無法可靠地儲存在裝置上。 Web 應用程式和 Web API 必須這麼做，這些應用程式和 Web API 能夠安全地將client_secret儲存在伺服器端。 |
grant_type |
必要 | 對於授權碼流程的這個部分，必須設定 refresh_token 為 。 |
refresh_token |
必要 | 您 在要求存取令牌時取得的refresh_token。 |
scope |
必要 | 以空格分隔的範圍清單。 此欄位中要求的範圍必須等同於或是您 要求使用者同意時所包含範圍的子集。 如果此要求中指定的範圍跨越多個資源伺服器，則 Microsoft 身分識別平台 端點會針對第一個範圍中指定的資源傳回令牌。 如需範圍的詳細說明，請參閱 許可權、同意和範圍。 |
tenant |
必要 | 要求 {tenant} 路徑中的值可用來控制誰可以登入應用程式。 為了確保您的應用程式同時支援 MSA 個人帳戶和 Azure AD 公司或學校帳戶，建議您使用 common 作為 Bing 廣告 API 驗證的租使用者。如果您的應用程式需要另一個租使用者，請參閱 Microsoft 身分識別平台 端點以取得詳細資訊。 |
雖然當用來取得新的存取令牌時，不會撤銷重新整理令牌，但您應該會捨棄舊的重新整理令牌。 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."}
請記住，公用重新整理令牌只會系結至授與的裝置。 例如，如果您註冊原生應用程式並使用 https://login.microsoftonline.com/common/oauth2/nativeclient 作為重新導向 URI，我們只保證它可以在相同的裝置上重新整理。 在跨 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 錯誤 和 驗證和授權錯誤碼。