Partilhar via

Fazer a sua primeira chamada à API

  • Artigo

Importante

Em junho de 2022, introduzimos a autenticação multifator como um requisito para anúncios do Bing. Poderá ainda ter de fazer uma alteração de código para se tornar compatível com este requisito. O Microsoft Advertising está a realizar verificações de imposição técnica no início de outubro.

Esta publicação de blogue descreve os passos que deve seguir para garantir a conformidade.

Para obter mais informações, veja o guia de requisitos de autenticação multifator .

Se apenas quiser que algo funcione imediatamente, siga estes passos para obter as suas informações de utilizador do Microsoft Advertising.

Guia de Introdução à Produção

Para se autenticar no ambiente de produção, primeiro deve registar uma aplicação. Inicie sessão com as credenciais da sua conta Microsoft e conceda o consentimento da sua aplicação para gerir as suas contas do Microsoft Advertising.

  1. Crie um novo ficheiro e cole-o no seguinte script. Defina $clientId como o ID da Aplicação da sua aplicação registada. Se registou uma aplicação Web com o segredo do cliente, também terá de incluir $client_secret=YourWebAppClientSecret quando pedir os tokens de acesso.

Nota

Substitua your_client_id abaixo pelo ID da aplicação (cliente) que o portal portal do Azure - Registos de aplicações atribuiu à sua aplicação.

```powershell
# 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
```

Save the file and name it `Get-Tokens-Production.ps1` (you can name it anything you want but the extension must be .ps1).

To programmatically manage a Microsoft Advertising account, you must provide consent at least once through the web application consent flow. From then on you can use the latest refresh token to request new access and refresh tokens without any further user interaction.

  1. Agora, para executar Get-Tokens-Production.ps1 , abra uma janela da consola. Na linha de comandos, navegue para a pasta onde guardou Get-Tokens-Production.ps1 e introduza o seguinte comando:

    powershell.exe -File .\Get-Tokens-Production.ps1

    Quando o script do PowerShell é executado com êxito, inicia uma sessão do browser onde introduz as credenciais do Microsoft Advertising. Após o consentimento, a barra de endereço do browser contém o código de concessão (consulte ?code=UseThisCode&...).

    https://login.microsoftonline.com/common/oauth2/nativeclient?code=M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143

    Copie o código de concessão (o seu próprio código, não o exemplo M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143) e introduza-o na janela da consola no pedido. Em seguida, o script do PowerShell devolve os tokens de acesso e atualização. (O script faz uma segunda chamada para Invoke-WebRequest como exemplo de como atualizar os tokens.) Deve tratar o token de atualização como se fosse uma palavra-passe; Se alguém conseguir, terá acesso aos seus recursos. O token de atualização é de longa duração, mas pode tornar-se inválido. Se alguma vez receber um erro de invalid_grant, o token de atualização já não é válido e terá de executar novamente o script do PowerShell para obter o Get-Tokens-Production.ps1 consentimento do utilizador e um novo token de atualização.

  2. Crie um novo ficheiro e cole-o no seguinte script. Defina o para o accessToken valor que Get-Tokens-Production.ps1 recebeu e defina $developerToken para o token de programador que recebeu ao seguir os passos descritos aqui.

    $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 o ficheiro e dê-lhe o Get-User.ps1 nome (pode dar-lhe o nome que quiser, mas a extensão tem de ser .ps1).

  3. Agora, para executar Get-User.ps1 , abra uma janela da consola. Na linha de comandos, navegue para a pasta onde guardou Get-User.ps1 e introduza o seguinte comando:

    powershell.exe -File .\Get-User.ps1

    Quando o script do PowerShell for executado com êxito, deverá imprimir os detalhes do utilizador do Microsoft Advertising, incluindo as funções de cliente. Para obter detalhes, veja GetUser.

Guia de Introdução do Sandbox

Para se autenticar no ambiente do sandbox, não precisa de registar uma aplicação. Basta utilizar o ID de cliente público "Tutorial Sample App", ou seja, 4c0b021c-00c3-4508-838f-d3127e8167ff.

  1. Inscreva-se numa conta sandbox do Microsoft Advertising . O endereço de e-mail da conta Microsoft (MSA) tem de ser outlook-int.com (por exemplo, someone@outlook-int.com). Para obter mais detalhes, consulte Sandbox.

  2. Crie um novo ficheiro e cole-o no seguinte script.

    # Replace the Tutorial Sample App ID with your registered application ID. 
$clientId = "4c0b021c-00c3-4508-838f-d3127e8167ff"

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 o ficheiro e dê-lhe o Get-Tokens-Sandbox.ps1 nome (pode dar-lhe o nome que quiser, mas a extensão tem de ser .ps1).

    Um utilizador tem de dar consentimento, pelo menos, uma vez através do fluxo de consentimento da aplicação Web. A partir daí, pode utilizar o token de atualização mais recente para pedir novos tokens de acesso e atualização sem qualquer interação adicional do utilizador.

  3. Agora, para executar Get-Tokens-Sandbox.ps1 , abra uma janela da consola. Na linha de comandos, navegue para a pasta onde guardou Get-Tokens-Sandbox.ps1 e introduza o seguinte comando:

    powershell.exe -File .\Get-Tokens-Sandbox.ps1

    Quando o script do PowerShell é executado com êxito, inicia uma sessão do browser onde introduz as credenciais do Microsoft Advertising. Após o consentimento, a barra de endereço do browser contém o código de concessão (consulte ?code=UseThisCode&...).

    https://login.windows-ppe.net/common/oauth2/nativeclient?code=M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009

    Copie o código de concessão (o seu próprio código, não o exemplo M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009) e introduza-o na janela da consola na linha de comandos. Em seguida, o script do PowerShell devolve os tokens de acesso e atualização. (O script faz uma segunda chamada para Invoke-WebRequest como exemplo de como atualizar os tokens.) Deve tratar o token de atualização como se fosse uma palavra-passe; Se alguém conseguir, terá acesso aos seus recursos. O token de atualização é de longa duração, mas pode tornar-se inválido. Se alguma vez receber um erro de invalid_grant, o token de atualização já não é válido e terá de executar novamente o script do PowerShell para obter o Get-Tokens-Sandbox.ps1 consentimento do utilizador e um novo token de atualização.

  4. Crie um novo ficheiro e cole-o no seguinte script. Defina o accessToken para o valor que recebeu 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 o ficheiro e dê-lhe o Get-User.ps1 nome (pode dar-lhe o nome que quiser, mas a extensão tem de ser .ps1).

  5. Agora, para executar Get-User.ps1 , abra uma janela da consola. Na linha de comandos, navegue para a pasta onde guardou Get-User.ps1 e introduza o seguinte comando:

    powershell.exe -File .\Get-User.ps1

    Quando o script do PowerShell for executado com êxito, deverá imprimir os detalhes do utilizador do Microsoft Advertising, incluindo as funções de cliente. Para obter detalhes, veja GetUser.

See Also

Introdução