共用方式為

進行您的第一個 API 呼叫

  • 發行項

重要事項

在 2022 年 6 月，我們引進了 多重要素驗證 作為Bing Ads的需求。 您可能仍然需要變更程序代碼，才能符合這項需求。 Microsoft Advertising 會在 10 月初執行技術強制檢查。

此部落格文章 概述您應該採取以確保合規性的步驟。

如需詳細資訊，請參閱 多重要素驗證需求 指南。

如果您只想要立即開始運作，請遵循下列步驟來取得Microsoft廣告用戶資訊。

生產快速入門

若要在生產環境中進行驗證，您應該先 註冊應用程式。 使用您的Microsoft帳戶認證登入，並授 與應用程式 管理Microsoft Advertising 帳戶的同意。

  1. 建立新的檔案，然後將下列腳本貼到其中。 設定 $clientId 為已註冊應用程式的應用程式識別碼。 如果您已向客戶端密碼註冊 Web 應用程式，則在要求存取權杖時也必須包含 $client_secret=YourWebAppClientSecret 。

注意事項

將以下your_client_id取代為應用程式 ( 用戶端) 標識符，Azure 入口網站 - 應用程式註冊 入口網站指派您的應用程式。

# 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

儲存盤案並將它 Get-Tokens-Production.ps1 命名 (您可以為它命名任何您想要的專案，但擴展名必須 .ps1) 。

若要以程式設計方式管理 Microsoft Advertising 帳戶，您必須透過 Web 應用程式同意流程至少提供一次同意。 之後，您可以使用最新的重新整理令牌來要求新的存取和重新整理令牌，而不需要任何進一步的用戶互動。

  1. 現在，若要執行 Get-Tokens-Production.ps1 ，請開啟主控台視窗。 在命令提示字元中，流覽至您儲存 Get-Tokens-Production.ps1 的資料夾，然後輸入下列命令：

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

    當 PowerShell 腳本成功執行時，它會啟動瀏覽器會話，您會在其中輸入Microsoft Advertising 認證。 同意之後，瀏覽器的網址列會包含授與碼 (請參閱 ？code=UseThisCode&...) 。

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

    將授與碼複製 (您自己的程序代碼，而不是範例 M.R4_BAY.f202904c-2269-4daf-1e21-862ed4d49143) ，並在提示字元的控制台視窗中輸入它。 然後，PowerShell 腳本會傳回存取和重新整理令牌。 (腳本會對 Invoke-WebRequest 進行第二次呼叫，作為如何重新整理令牌的範例。) 您應該將重新整理令牌視為密碼;如果有人擁有它，他們就可以存取您的資源。 重新整理令牌的存留期很長，但可能會變成無效。 如果您收到invalid_grant錯誤，重新整理令牌將不再有效，您必須再次執行 Get-Tokens-Production.ps1 PowerShell 腳本，以取得使用者同意和新的重新整理令牌。

  2. 建立新的檔案，然後將下列腳本貼到其中。 accessToken將 設定為您從 Get-Tokens-Production.ps1 收到的值，並依照這裡所述的步驟設定$developerToken為您收到的開發人員令牌。

    $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

    儲存盤案並將它 Get-User.ps1 命名 (您可以為它命名任何您想要的專案，但擴展名必須 .ps1) 。

  3. 現在，若要執行 Get-User.ps1 ，請開啟主控台視窗。 在命令提示字元中，流覽至您儲存 Get-User.ps1 的資料夾，然後輸入下列命令：

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

    PowerShell 腳本成功執行時，應該會列印出Microsoft Advertising 用戶的詳細數據，包括客戶角色。 如需詳細資訊 ，請參閱 GetUser。

沙箱快速入門

若要在沙箱環境中進行驗證，您不需要註冊應用程式。 只要使用公用的「教學課程範例應用程式」用戶端標識符，即 00001111-aaaa-2222-bbbb-3333cccc4444。

  1. 註冊 Microsoft Advertising 沙盒帳戶。 MSA) 電子郵件地址 (Microsoft帳戶必須是 outlook-int.com (例如 someone@outlook-int.com) 。 如需詳細資訊，請參閱 沙盒。

  2. 建立新的檔案，然後將下列腳本貼到其中。

    # 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

    儲存盤案並將它 Get-Tokens-Sandbox.ps1 命名 (您可以為它命名任何您想要的專案，但擴展名必須 .ps1) 。

    用戶必須透過 Web 應用程式同意流程至少提供一次同意。 之後，您可以使用最新的重新整理令牌來要求新的存取和重新整理令牌，而不需要任何進一步的用戶互動。

  3. 現在，若要執行 Get-Tokens-Sandbox.ps1 ，請開啟主控台視窗。 在命令提示字元中，流覽至您儲存 Get-Tokens-Sandbox.ps1 的資料夾，然後輸入下列命令：

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

    當 PowerShell 腳本成功執行時，它會啟動瀏覽器會話，您會在其中輸入Microsoft Advertising 認證。 同意之後，瀏覽器的網址列會包含授與碼 (請參閱 ？code=UseThisCode&...) 。

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

    將授與碼複製 (您自己的程序代碼，而不是範例 M.R0_CD1.132de532-5105-7550-b1fd-d37f9af2f009) ，並在提示字元的控制台視窗中輸入它。 然後，PowerShell 腳本會傳回存取和重新整理令牌。 (腳本會對 Invoke-WebRequest 進行第二次呼叫，作為如何重新整理令牌的範例。) 您應該將重新整理令牌視為密碼;如果有人擁有它，他們就可以存取您的資源。 重新整理令牌的存留期很長，但可能會變成無效。 如果您收到invalid_grant錯誤，重新整理令牌將不再有效，您必須再次執行 Get-Tokens-Sandbox.ps1 PowerShell 腳本，以取得使用者同意和新的重新整理令牌。

  4. 建立新的檔案，然後將下列腳本貼到其中。 accessToken將設定為您從 收到的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

    儲存盤案並將它 Get-User.ps1 命名 (您可以為它命名任何您想要的專案，但擴展名必須 .ps1) 。

  5. 現在，若要執行 Get-User.ps1 ，請開啟主控台視窗。 在命令提示字元中，流覽至您儲存 Get-User.ps1 的資料夾，然後輸入下列命令：

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

    PowerShell 腳本成功執行時，應該會列印出Microsoft Advertising 用戶的詳細數據，包括客戶角色。 如需詳細資訊 ，請參閱 GetUser。

另請參閱

開始使用