Effettuare la prima chiamata API

Articolo
07/07/2024

Importante

Nel giugno 2022 è stata introdotta l'autenticazione a più fattori come requisito per Bing Ads. Potrebbe comunque essere necessario apportare una modifica al codice per essere conforme a questo requisito. Microsoft Advertising esegue controlli tecnici all'inizio di ottobre.

Questo post di blog descrive i passaggi da eseguire per garantire la conformità.

Per altre informazioni, vedere la guida ai requisiti di autenticazione a più fattori .

Se vuoi semplicemente ottenere qualcosa che funzioni subito, segui questi passaggi per ottenere le informazioni degli utenti di Microsoft Advertising.

Avvio rapido per la produzione

Per eseguire l'autenticazione nell'ambiente di produzione, è necessario prima registrare un'applicazione. Accedere con le credenziali dell'account Microsoft e concedere il consenso dell'app per gestire gli account Microsoft Advertising.

Creare un nuovo file e incollarvi lo script seguente. Impostare sull'ID $clientId applicazione dell'app registrata. Se è stata registrata un'applicazione Web con il segreto client, sarà necessario includere $client_secret=YourWebAppClientSecret anche quando si richiedono i token di accesso.

Nota

Sostituire your_client_id seguente con l'ID applicazione (client) assegnato dall'portale di Azure al portale Registrazioni app.

# 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

Salvare il file e denominarlo Get-Tokens-Production.ps1 (è possibile denominarlo come desiderato, ma l'estensione deve essere .ps1).

Per gestire un account Microsoft Advertising a livello di codice, è necessario fornire il consenso almeno una volta tramite il flusso di consenso dell'applicazione Web. Da allora in poi è possibile usare il token di aggiornamento più recente per richiedere nuovi token di accesso e aggiornamento senza ulteriori interazioni con l'utente.

A questo scopo, Get-Tokens-Production.ps1 aprire una finestra della console. Al prompt dei comandi passare alla cartella in cui è stato salvato Get-Tokens-Production.ps1 e immettere il comando seguente:
```
powershell.exe -File .\Get-Tokens-Production.ps1
```
Quando lo script di PowerShell viene eseguito correttamente, avvia una sessione del browser in cui immettere le credenziali di Microsoft Advertising. Dopo il consenso, la barra degli indirizzi del browser contiene il codice di concessione (vedere ?code=UseThisCode&...).
```
https://login.microsoftonline.com/common/oauth2/nativeclient?code=M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143
```
Copiare il codice di concessione (il proprio codice, non l'esempio M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143) e immetterlo nella finestra della console al prompt. Lo script di PowerShell restituisce quindi i token di accesso e aggiornamento. Lo script esegue una seconda chiamata a Invoke-WebRequest come esempio di aggiornamento dei token. È consigliabile considerare il token di aggiornamento come se si trattasse di una password; se qualcuno ne entra in possesso, ha accesso alle risorse. Il token di aggiornamento è di lunga durata, ma può diventare non valido. Se si riceve un errore di invalid_grant, il token di aggiornamento non è più valido ed è necessario eseguire di nuovo lo Get-Tokens-Production.ps1 script di PowerShell per ottenere il consenso dell'utente e un nuovo token di aggiornamento.

Creare un nuovo file e incollarvi lo script seguente. Impostare sul accessToken valore ricevuto da Get-Tokens-Production.ps1 e impostare $developerToken sul token di sviluppo ricevuto seguendo i passaggi descritti qui.

$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

Salvare il file e denominarlo Get-User.ps1 (è possibile denominarlo come desiderato, ma l'estensione deve essere .ps1).

A questo scopo, Get-User.ps1 aprire una finestra della console. Al prompt dei comandi passare alla cartella in cui è stato salvato Get-User.ps1 e immettere il comando seguente:
```
powershell.exe -File .\Get-User.ps1
```
Quando lo script di PowerShell viene eseguito correttamente, deve stampare i dettagli dell'utente di Microsoft Advertising, inclusi i ruoli dei clienti. Per informazioni dettagliate, vedere GetUser.

Guida introduttiva alla sandbox

Per eseguire l'autenticazione nell'ambiente sandbox non è necessario registrare un'applicazione. È sufficiente usare l'ID client "Tutorial Sample App" pubblico, ad esempio 00001111-aaaa-2222-bbbb-3333cccc4444.

Iscriversi per ottenere un account sandbox di Microsoft Advertising . L'indirizzo di posta elettronica dell'account Microsoft (MSA) deve essere outlook-int.com , ad esempio someone@outlook-int.com. Per altri dettagli, vedere Sandbox.

Creare un nuovo file e incollarvi lo script seguente.

# 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

Salvare il file e denominarlo Get-Tokens-Sandbox.ps1 (è possibile denominarlo come desiderato, ma l'estensione deve essere .ps1).

Un utente deve fornire il consenso almeno una volta tramite il flusso di consenso dell'applicazione Web. Da allora in poi è possibile usare il token di aggiornamento più recente per richiedere nuovi token di accesso e aggiornamento senza ulteriori interazioni con l'utente.

A questo scopo, Get-Tokens-Sandbox.ps1 aprire una finestra della console. Al prompt dei comandi passare alla cartella in cui è stato salvato Get-Tokens-Sandbox.ps1 e immettere il comando seguente:
```
powershell.exe -File .\Get-Tokens-Sandbox.ps1
```
Quando lo script di PowerShell viene eseguito correttamente, avvia una sessione del browser in cui immettere le credenziali di Microsoft Advertising. Dopo il consenso, la barra degli indirizzi del browser contiene il codice di concessione (vedere ?code=UseThisCode&...).
```
https://login.windows-ppe.net/common/oauth2/nativeclient?code=M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009
```
Copiare il codice di concessione (il proprio codice, non l'esempio M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009) e immetterlo nella finestra della console al prompt. Lo script di PowerShell restituisce quindi i token di accesso e aggiornamento. Lo script esegue una seconda chiamata a Invoke-WebRequest come esempio di aggiornamento dei token. È consigliabile considerare il token di aggiornamento come se si trattasse di una password; se qualcuno ne entra in possesso, ha accesso alle risorse. Il token di aggiornamento è di lunga durata, ma può diventare non valido. Se si riceve un errore di invalid_grant, il token di aggiornamento non è più valido ed è necessario eseguire di nuovo lo Get-Tokens-Sandbox.ps1 script di PowerShell per ottenere il consenso dell'utente e un nuovo token di aggiornamento.

Creare un nuovo file e incollarvi lo script seguente. Impostare sul accessToken valore ricevuto da 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

Salvare il file e denominarlo Get-User.ps1 (è possibile denominarlo come desiderato, ma l'estensione deve essere .ps1).

A questo scopo, Get-User.ps1 aprire una finestra della console. Al prompt dei comandi passare alla cartella in cui è stato salvato Get-User.ps1 e immettere il comando seguente:
```
powershell.exe -File .\Get-User.ps1
```
Quando lo script di PowerShell viene eseguito correttamente, deve stampare i dettagli dell'utente di Microsoft Advertising, inclusi i ruoli dei clienti. Per informazioni dettagliate, vedere GetUser.

Vedere anche

Introduzione

Condividi tramite

Effettuare la prima chiamata API

Avvio rapido per la produzione

Guida introduttiva alla sandbox

Vedere anche

Commenti e suggerimenti

Risorse aggiuntive