Erişim ve yenileme belirteçlerini alma

Bir kullanıcı Microsoft Advertising hesabını yönetmeniz için onay verdikten sonra, erişim belirteci için yetkilendirmeyi code kullanabilirsiniz.

1. Kullanıcı onay verdikten sonra döndürüleni code kullanarak erişim belirteci isteyin. JSON yanıt akışından access_token, refresh_token ve expires_in değerlerini alın.
2. Erişim belirteci aldığınızda, expires_in değeri erişim belirtecinin süresi dolana kadar saniye cinsinden en uzun süreyi temsil eder. Erişim belirtecinin süresi dolmadan veya API erişimine yeniden ihtiyaç duymadan önce erişim belirtecini yenilemeniz gerekir.
3. başarıyla bir access_tokenedindikten sonra, Bing Ads API'lerine yönelik isteklerde belirteci kullanabilirsiniz . Örnek için İlk API çağrınızı yapma kılavuzuna bakın.

Yukarıdaki 1. ve 2. adımlara bir örnek aşağıda verilmiştır.

# 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

Erişim belirteci isteği ayrıntıları

için değerini istediğiniz kaynağa kullanabilirsiniz codeaccess_token . Uç noktaya bir POST istek /token göndererek bunu yapın:

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only applicable for web apps

İsteğin gövdesi istek parametrelerini içermelidir ve content-Type üst bilgisi application/x-www-form-urlencoded olarak ayarlanmalıdır. Kod parametresini önceki adımda alınan yetkilendirme kodunun değerine, verme türü ise authorization_code olarak ayarlayın. redirect_uri, yetkilendirme kodunu almak için kullanılan yeniden yönlendirme URI'sine tam olarak eşleşmelidir. Yeniden yönlendirme URL'sini kodlamayı unutmayın. Bir web uygulaması kaydettiyseniz , client_secret parametresini ekleyin ve uygulamayı kaydetme bölümünde sağlanan değere ayarlayın.

Aşağıdaki tablo, Bing Ads API istemcilerinin ilk erişim belirteci isteğine ekleyebilecekleri parametreleri içerir. İsteğe bağlı parametreler hakkında ek ayrıntılar için Microsoft kimlik platformu OAuth 2.0 yetkilendirme kodu akışı belgelerine bakın.

Belirteç isteği ayrıntılarını yenileme

Erişim belirteçleri kısa ömürlü olur ve kaynaklara erişmeye devam etmek için süresi dolduktan sonra bunları yenilemeniz gerekir. Bunu yapmak için /token uç noktaya başka bir POST istek gönderebilirsiniz ve bu kez yerine codeöğesini refresh_token sağlayabilirsiniz. Yenileme belirteçleri, istemcinizin zaten onay aldığı tüm izinler için geçerlidir.

Yenileme belirteçlerinin belirtilen yaşam süreleri yoktur. Genellikle yenileme belirteçlerinin ömrü nispeten uzun olur. Ancak bazı durumlarda yenileme belirteçlerinin süresi dolar, iptal edilir veya istenen eylem için yeterli ayrıcalıklara sahip değildir. Uygulamanızın belirteç verme uç noktası tarafından döndürülen hataları doğru şekilde beklemesi ve işlemesi gerekir. OAuth hataları hakkında daha fazla ayrıntı için bkz. Yaygın OAuth Hataları ve Kimlik Doğrulaması ve yetkilendirme hata kodları.

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only applicable for web apps

İsteğin gövdesi istek parametrelerini içermelidir ve content-Type üst bilgisi application/x-www-form-urlencoded olarak ayarlanmalıdır. Yenileme belirteci parametresini önceki adımda alınan yenileme belirtecinin değerine, verme türü ise refresh_token olarak ayarlayın. Bir web uygulaması kaydettiyseniz , client_secret parametresini ekleyin ve uygulamayı kaydetme bölümünde sağlanan değere ayarlayın.

Aşağıdaki tabloda, Bing Ads API istemcilerinin erişim belirtecini yenileme isteğine ekleyebilecekleri parametreler yer alır. İsteğe bağlı parametreler hakkında ek ayrıntılar için Microsoft kimlik platformu OAuth 2.0 yetkilendirme kodu akışı belgelerine bakın.

Yeni erişim belirteçleri almak için kullanıldığında yenileme belirteçleri iptal edilmese de, eski yenileme belirtecini atmanız beklenir. OAuth 2.0 belirtimi şunları söyler: "Yetkilendirme sunucusu yeni bir yenileme belirteci verebilir; bu durumda istemcinin eski yenileme belirtecini atması ve yeni yenileme belirteci ile değiştirmesi GEREKIR. Yetkilendirme sunucusu, istemciye yeni bir yenileme belirteci verdikten sonra eski yenileme belirtecini iptal edebilir."

Yenileme belirteçleri uygulamanız için tamamen donuk ve her zaman olacaktır. Bunlar, genel istemciler için 90 gün gibi uzun sürelidir, ancak bir yenileme belirtecinin herhangi bir süre boyunca süreceğini beklemek için uygulama yazılmamalıdır. Yenileme belirteçleri her an geçersiz kılınabilir ve bir uygulamanın yenileme belirtecinin geçerli olup olmadığını bilmesinin tek yolu belirteç isteğinde bulunarak bunu kullanmaya çalışmaktır. Aynı cihazdaki belirteci en son yenileme belirteci ile sürekli yenileseniz bile, örneğin Microsoft Advertising kullanıcısı parolasını değiştirdiyse, güvenilir cihazlar listesinden bir cihazı kaldırdıysa veya uygulamanızın kendi adına kimlik doğrulaması için izinlerini kaldırdıysa, yeniden başlamayı ve kullanıcı onayı istemeyi beklemeniz gerekir. Microsoft, önceden uyarı vermeden herhangi bir zamanda kullanıcı onayının yeniden verilmesi gerektiğini belirleyebilir. Bu durumda, yetkilendirme hizmeti aşağıdaki örnekte gösterildiği gibi geçersiz bir verme hatası döndürür.

{"error":"invalid_grant","error_description":"The user could not be authenticated or the grant is expired. The user must first sign in and if needed grant the client application access to the requested scope."}

Genel yenileme belirteçlerinin yalnızca verilen cihaza bağlı olduğunu unutmayın. Örneğin, yerel bir uygulama kaydettiyseniz ve yeniden yönlendirme URI'sini kullandıysanız https://login.microsoftonline.com/common/oauth2/nativeclient , yalnızca aynı cihazda yenilenebileceğini garanti ederiz. Microsoft Azure gibi bölgelere ve cihazlara yayılan hizmetlerde uygulama çalıştıran istemcilerin bir Web uygulamasını istemci gizli dizisiyle kaydetmesi gerekir. Yeniden yönlendirme URI'si localhost olabilir ancak olamaz https://login.microsoftonline.com/common/oauth2/nativeclient. Bir istemci gizli dizisiyle kullanırsanız https://login.microsoftonline.com/common/oauth2/nativeclient aşağıdaki hata döndürülür.

{"error":"invalid_request","error_description":"Public clients can't send a client secret."} Likewise for Web apps please note that refresh tokens can be invalidated at any moment.

İstemci gizli dizisi olmadan sağlanan bir yenileme belirteci kullanarak yeni erişim ve yenileme belirteçleri istemeye çalışırsanız aynı hatayla karşılaşırsınız.

OAuth hataları hakkında daha fazla ayrıntı için bkz. Yaygın OAuth Hataları ve Kimlik Doğrulaması ve yetkilendirme hata kodları.

Sonraki adımlar

Ayrıca Bkz

Başlarken