获取访问和刷新令牌
重要
2022 年 6 月，我们引入了 多重身份验证 作为必应广告的要求。 可能需要更改代码才能符合此要求。 Microsoft Advertising 在 10 月初执行技术强制检查。
此博客文章 概述了确保合规性应采取的步骤。
有关详细信息，请参阅 多重身份验证要求 指南。
用户授予你管理其 Microsoft Advertising 帐户的许可后，你可以兑换访问令牌的授权 code 。
- 通过兑换
code在用户授予同意后返回的 来请求访问令牌。 从 JSON 响应流中获取 access_token、 refresh_token和 expires_in 值。 - 收到访问令牌时， expires_in 的值表示访问令牌过期前的最长时间（以秒为单位）。 在访问令牌过期或再次需要 API 访问之前，应 刷新访问令牌。
- 成功获取
access_token后 ，可以在对 必应广告 API 的请求中使用令牌。 有关示例，请参阅 创建第一个 API 调用 指南。
下面是上述步骤 1 和步骤 2 的示例。
注意
将下面的your_client_id替换为Azure 门户 -应用注册门户分配应用的应用程序 (客户端) 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 错误 指南。
访问令牌请求详细信息
可以将 兑换 code 到 access_token 所需资源的 。 通过向/token终结点发送POST请求来执行此操作：
注意
将下面的your_client_id替换为Azure 门户 -应用注册门户分配应用的应用程序 (客户端) 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。 将代码参数设置为在上一步中检索的授权代码的值，并将授权类型设置为 authorization_code。 redirect_uri必须与用于获取授权代码的重定向 URI 完全匹配。 请务必对重定向 URL 进行编码。 如果注册了 Web 应用程序，请包含 client_secret 参数，并将其设置为 注册应用程序中预配的值。
下表包含必应广告 API 客户端可以包含在初始访问令牌请求中的参数。 有关可选参数的其他详细信息，请参阅Microsoft 标识平台 OAuth 2.0 授权代码流文档。
| 参数 | 必需/可选 | 说明 |
|---|---|---|
client_id |
必需 | 应用程序 (客户端) 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 作为必应广告 API 身份验证的租户。如果应用程序需要另一个租户，请参阅Microsoft 标识平台终结点了解详细信息。 |
刷新令牌请求详细信息
访问令牌生存期较短，必须在令牌过期后对其进行刷新才能继续访问资源。 为此，可以向终结点提交另一个 POST 请求 /token ，这次提供 refresh_token 而不是 code。 刷新令牌对客户端已获得同意的所有权限有效。
刷新令牌没有指定的生存期。 通常，刷新令牌的生存期相对较长。 但是，在某些情况下，刷新令牌过期、被吊销或缺少所需操作的足够权限。 应用程序需要正确处理令牌颁发终结点返回的错误。 有关 OAuth 错误的更多详细信息，请参阅 常见 OAuth 错误 和 身份验证和授权错误代码。
注意
将下面的your_client_id替换为Azure 门户 -应用注册门户分配应用的应用程序 (客户端) 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 参数，并将其设置为 注册应用程序中预配的值。
下表包含必应广告 API 客户端可以包含在刷新访问令牌的请求中的参数。 有关可选参数的其他详细信息，请参阅Microsoft 标识平台 OAuth 2.0 授权代码流文档。
| 参数 | 必需/可选 | 说明 |
|---|---|---|
client_id |
必需 | 应用程序 (客户端) 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 作为必应广告 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 错误 和 身份验证和授权错误代码。