Tätigen Ihres ersten API-Aufrufs

Artikel
07/07/2024

Wichtig

Im Juni 2022 haben wir die mehrstufige Authentifizierung als Anforderung für Bing Ads eingeführt. Möglicherweise müssen Sie dennoch eine Codeänderung vornehmen, um diese Anforderung erfüllen zu können. Microsoft Advertising führt Anfang Oktober technische Erzwingungsprüfungen durch.

In diesem Blogbeitrag werden die Schritte beschrieben, die Sie ausführen sollten, um die Konformität sicherzustellen.

Weitere Informationen finden Sie im Anforderungsleitfaden für die mehrstufige Authentifizierung .

Wenn Sie nur möchten, dass etwas sofort funktioniert, führen Sie die folgenden Schritte aus, um Ihre Microsoft Advertising-Benutzerinformationen abzurufen.

Schnellstart für die Produktion

Um sich in der Produktionsumgebung zu authentifizieren, sollten Sie zuerst eine Anwendung registrieren. Melden Sie sich mit den Anmeldeinformationen Ihres Microsoft-Kontos an, und erteilen Sie Ihrer App die Zustimmung zur Verwaltung Ihrer Microsoft Advertising-Konten.

Erstellen Sie eine neue Datei, und fügen Sie das folgende Skript ein. Legen Sie auf die Anwendungs-ID Ihrer registrierten App fest $clientId . Wenn Sie eine Webanwendung mit einem geheimen Clientschlüssel registriert haben, müssen Sie beim Anfordern der Zugriffstoken auch einschließen $client_secret=YourWebAppClientSecret .

Hinweis

Ersetzen Sie your_client_id unten durch die Anwendungs-ID (Client), die Azure-Portal App-Registrierungen Portal Ihrer App zugewiesen wurde.

# 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

Speichern Sie die Datei, und benennen Sie sie Get-Tokens-Production.ps1 (Sie können sie beliebig benennen, aber die Erweiterung muss .ps1 sein).

Zum programmgesteuerten Verwalten eines Microsoft Advertising-Kontos müssen Sie die Zustimmung mindestens einmal über den Einwilligungsflow der Webanwendung erteilen. Ab dann können Sie das neueste Aktualisierungstoken verwenden, um neue Zugriffs- und Aktualisierungstoken ohne weitere Benutzerinteraktion anzufordern.

Öffnen Sie nun zum Ausführen Get-Tokens-Production.ps1 ein Konsolenfenster. Navigieren Sie an der Eingabeaufforderung zu dem Ordner, in dem Sie gespeichert haben Get-Tokens-Production.ps1 , und geben Sie den folgenden Befehl ein:
```
powershell.exe -File .\Get-Tokens-Production.ps1
```
Wenn das PowerShell-Skript erfolgreich ausgeführt wird, wird eine Browsersitzung gestartet, in der Sie Ihre Microsoft Advertising-Anmeldeinformationen eingeben. Nach der Zustimmung enthält die Adressleiste des Browsers den Genehmigungscode (siehe ?code=UseThisCode&...).
```
https://login.microsoftonline.com/common/oauth2/nativeclient?code=M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143
```
Kopieren Sie den Genehmigungscode (Ihren eigenen Code, nicht das Beispiel M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143), und geben Sie ihn an der Eingabeaufforderung in das Konsolenfenster ein. Das PowerShell-Skript gibt dann die Zugriffs- und Aktualisierungstoken zurück. (Das Skript führt einen zweiten Aufruf von Invoke-WebRequest als Beispiel für die Aktualisierung der Token durch.) Sie sollten das Aktualisierungstoken wie ein Kennwort behandeln. Wenn jemand es in den Besitz bekommt, hat er Zugriff auf Ihre Ressourcen. Das Aktualisierungstoken ist langlebig, kann aber ungültig werden. Wenn Sie jemals einen invalid_grant Fehler erhalten, ist Ihr Aktualisierungstoken nicht mehr gültig, und Sie müssen das PowerShell-Skript erneut ausführen, um die Get-Tokens-Production.ps1 Benutzereinwilligung und ein neues Aktualisierungstoken zu erhalten.

Erstellen Sie eine neue Datei, und fügen Sie das folgende Skript ein. Legen Sie auf accessToken den Wert fest, den Sie von Get-Tokens-Production.ps1 erhalten haben, und legen Sie auf das Entwicklertoken fest $developerToken , das Sie erhalten haben, indem Sie die hier beschriebenen Schritte ausführen.

$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

Speichern Sie die Datei, und benennen Sie sie Get-User.ps1 (Sie können sie beliebig benennen, aber die Erweiterung muss .ps1 sein).

Öffnen Sie nun zum Ausführen Get-User.ps1 ein Konsolenfenster. Navigieren Sie an der Eingabeaufforderung zu dem Ordner, in dem Sie gespeichert haben Get-User.ps1 , und geben Sie den folgenden Befehl ein:
```
powershell.exe -File .\Get-User.ps1
```
Wenn das PowerShell-Skript erfolgreich ausgeführt wird, sollte es die Details Ihres Microsoft Advertising-Benutzers ausgeben, einschließlich der Kundenrollen. Weitere Informationen finden Sie unter GetUser.

Sandbox-Schnellstart

Um sich in der Sandboxumgebung zu authentifizieren, müssen Sie keine Anwendung registrieren. Verwenden Sie einfach die öffentliche Client-ID "Tutorial Sample App", d. h. 00001111-aaaa-2222-bbbb-3333cccccc4444.

Registrieren Sie sich für ein Microsoft Advertising-Sandboxkonto . Die E-Mail-Adresse des Microsoft-Kontos (MSA) muss outlook-int.com sein (z. B someone@outlook-int.com. ). Weitere Informationen finden Sie unter Sandbox.

Erstellen Sie eine neue Datei, und fügen Sie das folgende Skript ein.

# 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

Speichern Sie die Datei, und benennen Sie sie Get-Tokens-Sandbox.ps1 (Sie können sie beliebig benennen, aber die Erweiterung muss .ps1 sein).

Ein Benutzer muss die Zustimmung mindestens einmal über den Webanwendungs-Einwilligungsflow erteilen. Ab dann können Sie das neueste Aktualisierungstoken verwenden, um neue Zugriffs- und Aktualisierungstoken ohne weitere Benutzerinteraktion anzufordern.

Öffnen Sie nun zum Ausführen Get-Tokens-Sandbox.ps1 ein Konsolenfenster. Navigieren Sie an der Eingabeaufforderung zu dem Ordner, in dem Sie gespeichert haben Get-Tokens-Sandbox.ps1 , und geben Sie den folgenden Befehl ein:
```
powershell.exe -File .\Get-Tokens-Sandbox.ps1
```
Wenn das PowerShell-Skript erfolgreich ausgeführt wird, wird eine Browsersitzung gestartet, in der Sie Ihre Microsoft Advertising-Anmeldeinformationen eingeben. Nach der Zustimmung enthält die Adressleiste des Browsers den Genehmigungscode (siehe ?code=UseThisCode&...).
```
https://login.windows-ppe.net/common/oauth2/nativeclient?code=M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009
```
Kopieren Sie den Genehmigungscode (Ihren eigenen Code, nicht das Beispiel M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009), und geben Sie ihn an der Eingabeaufforderung in das Konsolenfenster ein. Das PowerShell-Skript gibt dann die Zugriffs- und Aktualisierungstoken zurück. (Das Skript führt einen zweiten Aufruf von Invoke-WebRequest als Beispiel für die Aktualisierung der Token durch.) Sie sollten das Aktualisierungstoken wie ein Kennwort behandeln. Wenn jemand es in den Besitz bekommt, hat er Zugriff auf Ihre Ressourcen. Das Aktualisierungstoken ist langlebig, kann aber ungültig werden. Wenn Sie jemals einen invalid_grant Fehler erhalten, ist Ihr Aktualisierungstoken nicht mehr gültig, und Sie müssen das PowerShell-Skript erneut ausführen, um die Get-Tokens-Sandbox.ps1 Benutzereinwilligung und ein neues Aktualisierungstoken zu erhalten.

Erstellen Sie eine neue Datei, und fügen Sie das folgende Skript ein. Legen Sie auf accessToken den Wert fest, den Sie von Get-Tokens-Sandbox.ps1erhalten haben.

$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

Speichern Sie die Datei, und benennen Sie sie Get-User.ps1 (Sie können sie beliebig benennen, aber die Erweiterung muss .ps1 sein).

Öffnen Sie nun zum Ausführen Get-User.ps1 ein Konsolenfenster. Navigieren Sie an der Eingabeaufforderung zu dem Ordner, in dem Sie gespeichert haben Get-User.ps1 , und geben Sie den folgenden Befehl ein:
```
powershell.exe -File .\Get-User.ps1
```
Wenn das PowerShell-Skript erfolgreich ausgeführt wird, sollte es die Details Ihres Microsoft Advertising-Benutzers ausgeben, einschließlich der Kundenrollen. Weitere Informationen finden Sie unter GetUser.

Siehe auch

Erste Schritte

Freigeben über

Tätigen Ihres ersten API-Aufrufs

Schnellstart für die Produktion

Sandbox-Schnellstart

Siehe auch

Feedback

Zusätzliche Ressourcen