Erişim ve yenileme belirteçlerini alma

Önemli

Haziran 2022'de Bing Ads için çok faktörlü kimlik doğrulamasını zorunlu kıldık. Bu gereksinimle uyumlu olmak için yine de kod değişikliği yapmanız gerekebilir. Microsoft Advertising, Ekim ayının başlarında teknik uygulama denetimleri gerçekleştiriyor.

Bu blog gönderisinde uyumluluğu sağlamak için gerçekleştirmeniz gereken adımlar özetlenmiştir.

Daha fazla bilgi için çok faktörlü kimlik doğrulama gereksinimi kılavuzuna bakın.

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.

Not

Aşağıdaki your_client_id Azure portal - Uygulama kayıtları portalının uygulamanızı atadığı uygulama (istemci) kimliğiyle değiştirin.

# 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

İpucu

Sorun giderme yardımı için Yaygın OAuth hataları kılavuzuna bakın.

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:

Not

Aşağıdaki your_client_id Azure portal - Uygulama kayıtları portalının uygulamanızı atadığı uygulama (istemci) kimliğiyle değiştirin.

// 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.

Parametre	Gerekli/İsteğe Bağlı	Açıklama
client_id	Gerekli	Azure portal - Uygulama kayıtları portalının uygulamanızı atadığı uygulama (istemci) kimliği.
client_secret	web uygulamaları için gereklidir	Uygulamanız için uygulama kayıt portalında oluşturduğunuz uygulama gizli dizisi. Client_secrets cihazlarda güvenilir bir şekilde depolanamayacağından yerel uygulamada kullanılmamalıdır. client_secret sunucu tarafında güvenli bir şekilde depolama özelliğine sahip web uygulamaları ve web API'leri için gereklidir. İstemci gizli dizisi gönderilmeden önce URL ile kodlanmalıdır.
code	Gerekli	Kullanıcı onayı istemenin bir sonucu olarak edindiğiniz authorization_code.
code_verifier	Önerilen	authorization_code elde etmek için kullanılan code_verifier. Yetkilendirme kodu verme isteğinde PKCE kullanıldıysa gereklidir. Daha fazla bilgi için bkz. PKCE RFC.
grant_type	Gerekli	Yetkilendirme kodu akışı için olmalıdır authorization_code .
redirect_uri	Gerekli	authorization_code almak için kullanılan aynı redirect_uri değeri.
scope	Gerekli	Boşlukla ayrılmış kapsam listesi. Bu bacakta istenen kapsamlar , kullanıcı onayı istediğinizde dahil edilen kapsamların bir alt kümesi veya ile eşdeğer olmalıdır. Bu istekte belirtilen kapsamlar birden çok kaynak sunucusuna yayılmışsa, Microsoft kimlik platformu uç noktası ilk kapsamda belirtilen kaynak için bir belirteç döndürür. Kapsamların daha ayrıntılı açıklaması için izinler, onay ve kapsamlara bakın.
tenant	Gerekli	{tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Uygulamanızın hem MSA kişisel hesaplarını hem de Azure AD iş veya okul hesaplarını desteklediğinden emin olmak için Bing Ads API kimlik doğrulaması için kiracı olarak kullanmanızı common öneririz. Uygulamanızın başka bir kiracı gerektirmesi durumunda daha fazla bilgi için bkz. Microsoft kimlik platformu uç noktaları.

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ı.

Not

Aşağıdaki your_client_id Azure portal - Uygulama kayıtları portalının uygulamanızı atadığı uygulama (istemci) kimliğiyle değiştirin.

// 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.

Parametre	Gerekli/İsteğe Bağlı	Açıklama
client_id	Gerekli	Azure portal - Uygulama kayıtları portalının uygulamanızı atadığı uygulama (istemci) kimliği.
client_secret	web uygulamaları için gereklidir	Uygulamanız için uygulama kayıt portalında oluşturduğunuz uygulama gizli dizisi. Client_secrets cihazlarda güvenilir bir şekilde depolanamayacağından yerel uygulamada kullanılmamalıdır. client_secret sunucu tarafında güvenli bir şekilde depolama özelliğine sahip web uygulamaları ve web API'leri için gereklidir.
grant_type	Gerekli	Yetkilendirme kodu akışının bu ayağı için olarak ayarlanmalıdır refresh_token .
refresh_token	Gerekli	Erişim belirteci istediğinizde aldığınız refresh_token.
scope	Gerekli	Boşlukla ayrılmış kapsam listesi. Bu bacakta istenen kapsamlar , kullanıcı onayı istediğinizde dahil edilen kapsamların bir alt kümesi veya ile eşdeğer olmalıdır. Bu istekte belirtilen kapsamlar birden çok kaynak sunucusuna yayılmışsa, Microsoft kimlik platformu uç noktası ilk kapsamda belirtilen kaynak için bir belirteç döndürür. Kapsamların daha ayrıntılı açıklaması için izinler, onay ve kapsamlara bakın.
tenant	Gerekli	{tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. Uygulamanızın hem MSA kişisel hesaplarını hem de Azure AD iş veya okul hesaplarını desteklediğinden emin olmak için Bing Ads API kimlik doğrulaması için kiracı olarak kullanmanızı common öneririz. Uygulamanızın başka bir kiracı gerektirmesi durumunda daha fazla bilgi için bkz. Microsoft kimlik platformu uç noktaları.

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

İlk API çağrınızı yapma

Ayrıca Bkz

Başlarken