Realización de la primera llamada API

Artículo
11/13/2024

Importante

En junio de 2022, introdujimos la autenticación multifactor como requisito para Bing Ads. Es posible que tenga que realizar un cambio de código para cumplir con este requisito. Microsoft Advertising está realizando comprobaciones técnicas de cumplimiento a principios de octubre.

En esta entrada de blog se describen los pasos que debe seguir para garantizar el cumplimiento.

Para obtener más información, consulte la guía de requisitos de autenticación multifactor .

Si solo quiere que algo funcione de inmediato, siga estos pasos para obtener la información de usuario de Microsoft Advertising.

Inicio rápido de producción

Para autenticarse en el entorno de producción, primero debe registrar una aplicación. Inicie sesión con sus credenciales de cuenta de Microsoft y conceda su consentimiento a la aplicación para administrar sus cuentas de Microsoft Advertising.

Cree un nuevo archivo y péguelo en el siguiente script. Establezca $clientId en el identificador de aplicación de la aplicación registrada. Si registró una aplicación web con el secreto de cliente, también deberá incluir $client_secret=YourWebAppClientSecret al solicitar los tokens de acceso.

Nota:

Reemplace your_client_id siguiente por el identificador de aplicación (cliente) que el portal de Azure Portal Registros de aplicaciones asignó a la aplicación.

# 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

Guarde el archivo y asígnele Get-Tokens-Production.ps1 el nombre (puede asignarle el nombre que desee, pero la extensión debe estar .ps1).

Para administrar mediante programación una cuenta de Microsoft Advertising, debe proporcionar su consentimiento al menos una vez a través del flujo de consentimiento de la aplicación web. A partir de entonces, puede usar el token de actualización más reciente para solicitar nuevos tokens de acceso y actualización sin ninguna interacción adicional del usuario.

Ahora para ejecutar Get-Tokens-Production.ps1 , abra una ventana de consola. En el símbolo del sistema, vaya a la carpeta donde guardó Get-Tokens-Production.ps1 y escriba el siguiente comando:
```
powershell.exe -File .\Get-Tokens-Production.ps1
```
Cuando el script de PowerShell se ejecuta correctamente, se inicia una sesión del explorador en la que se escriben las credenciales de Microsoft Advertising. Después de dar su consentimiento, la barra de direcciones del explorador contiene el código de concesión (vea ?code=UseThisCode&...).
```
https://login.microsoftonline.com/common/oauth2/nativeclient?code=M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143
```
Copie el código de concesión (su propio código, no el ejemplo M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143) y introdúzcalo en la ventana de la consola en el símbolo del sistema. A continuación, el script de PowerShell devuelve los tokens de acceso y actualización. (El script realiza una segunda llamada a Invoke-WebRequest como ejemplo de cómo actualizar los tokens). Debe tratar el token de actualización como lo haría con una contraseña; si alguien se queda con ella, tiene acceso a los recursos. El token de actualización es de larga duración, pero puede dejar de ser válido. Si alguna vez recibe un error de invalid_grant, el token de actualización ya no es válido y tendrá que volver a ejecutar el Get-Tokens-Production.ps1 script de PowerShell para obtener el consentimiento del usuario y un nuevo token de actualización.

Cree un nuevo archivo y péguelo en el siguiente script. Establezca en el accessToken valor que recibió de Get-Tokens-Production.ps1 y establezca $developerToken en el token de desarrollador que recibió siguiendo los pasos descritos aquí.

$accessToken = "AccessTokenGoesHere";
$developerToken = "DeveloperTokenGoesHere";

[xml]$getUserRequest = 
'<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v13="https://bingads.microsoft.com/Customer/v13">
<soapenv:Header>
   <v13:DeveloperToken>{0}</v13:DeveloperToken>
   <v13:AuthenticationToken>{1}</v13:AuthenticationToken>
</soapenv:Header>
<soapenv:Body>
   <v13:GetUserRequest>
      <v13:UserId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
   </v13:GetUserRequest>
</soapenv:Body>
</soapenv:Envelope>' -f $developerToken, $accessToken

$headers = @{"SOAPAction" = "GetUser"}

$uri = "https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc"
$response = Invoke-WebRequest $uri -Method post -ContentType 'text/xml' -Body $getUserRequest -Headers $headers
Write-Output $response.Content

Guarde el archivo y asígnele Get-User.ps1 el nombre (puede asignarle el nombre que desee, pero la extensión debe estar .ps1).

Ahora para ejecutar Get-User.ps1 , abra una ventana de consola. En el símbolo del sistema, vaya a la carpeta donde guardó Get-User.ps1 y escriba el siguiente comando:
```
powershell.exe -File .\Get-User.ps1
```
Cuando el script de PowerShell se ejecuta correctamente, debe imprimir los detalles del usuario de Microsoft Advertising, incluidos los roles de cliente. Para obtener más información, consulte GetUser.

Inicio rápido del espacio aislado

Para autenticarse en el entorno de espacio aislado, no es necesario registrar una aplicación. Solo tiene que usar el identificador de cliente público "Aplicación de ejemplo de tutorial", es decir, 00001111-aaaa-2222-bbbb-3333cccc4444.

Regístrese para obtener una cuenta de espacio aislado de Microsoft Advertising . La dirección de correo electrónico de la cuenta microsoft (MSA) debe ser outlook-int.com (por ejemplo, someone@outlook-int.com). Para obtener más información, consulte Espacio aislado.

Cree un nuevo archivo y péguelo en el siguiente script.

# Replace the Tutorial Sample App ID with your registered application ID. 
$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444"

Start-Process "https://login.windows-ppe.net/consumers/oauth2/v2.0/authorize?client_id=$clientId&scope=openid%20profile%20https://api.ads.microsoft.com/msads.manage%20offline_access&response_type=code&redirect_uri=https://login.windows-ppe.net/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.windows-ppe.net/consumers/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://api.ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=authorization_code&redirect_uri=https://login.windows-ppe.net/common/oauth2/nativeclient"

$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.windows-ppe.net/consumers/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://api.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

Guarde el archivo y asígnele Get-Tokens-Sandbox.ps1 el nombre (puede asignarle el nombre que desee, pero la extensión debe estar .ps1).

Un usuario debe proporcionar el consentimiento al menos una vez a través del flujo de consentimiento de la aplicación web. A partir de entonces, puede usar el token de actualización más reciente para solicitar nuevos tokens de acceso y actualización sin ninguna interacción adicional del usuario.

Ahora para ejecutar Get-Tokens-Sandbox.ps1 , abra una ventana de consola. En el símbolo del sistema, vaya a la carpeta donde guardó Get-Tokens-Sandbox.ps1 y escriba el siguiente comando:
```
powershell.exe -File .\Get-Tokens-Sandbox.ps1
```
Cuando el script de PowerShell se ejecuta correctamente, se inicia una sesión del explorador en la que se escriben las credenciales de Microsoft Advertising. Después de dar su consentimiento, la barra de direcciones del explorador contiene el código de concesión (vea ?code=UseThisCode&...).
```
https://login.windows-ppe.net/common/oauth2/nativeclient?code=M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009
```
Copie el código de concesión (su propio código, no el ejemplo M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009) y introdúzcalo en la ventana de consola en el símbolo del sistema. A continuación, el script de PowerShell devuelve los tokens de acceso y actualización. (El script realiza una segunda llamada a Invoke-WebRequest como ejemplo de cómo actualizar los tokens). Debe tratar el token de actualización como lo haría con una contraseña; si alguien se queda con ella, tiene acceso a los recursos. El token de actualización es de larga duración, pero puede dejar de ser válido. Si alguna vez recibe un error de invalid_grant, el token de actualización ya no es válido y tendrá que volver a ejecutar el Get-Tokens-Sandbox.ps1 script de PowerShell para obtener el consentimiento del usuario y un nuevo token de actualización.

Cree un nuevo archivo y péguelo en el siguiente script. Establezca en accessToken el valor que recibió de Get-Tokens-Sandbox.ps1.

$accessToken = "AccessTokenGoesHere";
$developerToken = "BBD37VB98";

[xml]$getUserRequest = 
'<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v13="https://bingads.microsoft.com/Customer/v13">
<soapenv:Header>
   <v13:DeveloperToken>{0}</v13:DeveloperToken>
   <v13:AuthenticationToken>{1}</v13:AuthenticationToken>
</soapenv:Header>
<soapenv:Body>
   <v13:GetUserRequest>
      <v13:UserId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
   </v13:GetUserRequest>
</soapenv:Body>
</soapenv:Envelope>' -f $developerToken, $accessToken

$headers = @{"SOAPAction" = "GetUser"}

$uri = "https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc"
$response = Invoke-WebRequest $uri -Method post -ContentType 'text/xml' -Body $getUserRequest -Headers $headers
Write-Output $response.Content

Guarde el archivo y asígnele Get-User.ps1 el nombre (puede asignarle el nombre que desee, pero la extensión debe estar .ps1).

Ahora para ejecutar Get-User.ps1 , abra una ventana de consola. En el símbolo del sistema, vaya a la carpeta donde guardó Get-User.ps1 y escriba el siguiente comando:
```
powershell.exe -File .\Get-User.ps1
```
Cuando el script de PowerShell se ejecuta correctamente, debe imprimir los detalles del usuario de Microsoft Advertising, incluidos los roles de cliente. Para obtener más información, consulte GetUser.

Consulta también

Introducción

Compartir a través de

Realización de la primera llamada API

Inicio rápido de producción

Inicio rápido del espacio aislado

Consulta también

Comentarios

Recursos adicionales