Obtenir des jetons d’accès et d’actualisation

Une fois qu’un utilisateur a donné son consentement pour gérer son compte Microsoft Advertising, vous pouvez utiliser l’autorisation code contre un jeton d’accès.

1. Demandez un jeton d’accès en échangeant le code retourné après que l’utilisateur a accordé son consentement. Obtenez les valeurs access_token, refresh_token et expires_in à partir du flux de réponse JSON.
2. Lorsque vous avez reçu un jeton d’accès, la valeur de expires_in représente la durée maximale en secondes, jusqu’à l’expiration du jeton d’accès. Avant l’expiration du jeton d’accès ou avant que vous n’ayez à nouveau besoin d’un accès à l’API, vous devez actualiser le jeton d’accès.
3. Une fois que vous avez acquis un access_token, vous pouvez utiliser le jeton dans les requêtes adressées aux API Bing Ads. Consultez le guide Créer votre premier appel d’API pour obtenir un exemple.

Voici un exemple des étapes 1 et 2 ci-dessus.

# 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

Détails de la demande de jeton d’accès

Vous pouvez échanger contre code un access_token pour la ressource souhaitée. Pour ce faire, envoyez une POST requête au point de /token terminaison :

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

Le corps de la demande doit inclure les paramètres de la requête et l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded. Définissez le paramètre de code sur la valeur du code d’autorisation récupéré à l’étape précédente, et le type d’octroi défini sur authorization_code. Le redirect_uri doit correspondre exactement à l’URI de redirection utilisé pour obtenir le code d’autorisation. Veillez à encoder l’URL de redirection. Si vous avez inscrit une application web, incluez le paramètre client_secret et définissez-le sur la valeur provisionnée dans Inscrire une application.

Le tableau suivant inclut les paramètres que les clients de l’API Bing Ads peuvent inclure dans la demande de jeton d’accès initial. Pour plus d’informations sur les paramètres facultatifs, consultez la documentation sur le flux de code d’autorisation Plateforme d'identités Microsoft OAuth 2.0.

Détails de la demande de jeton d’actualisation

Les jetons d’accès sont de courte durée et vous devez les actualiser après leur expiration pour continuer à accéder aux ressources. Pour ce faire, envoyez une autre POST demande au /token point de terminaison, en fournissant cette fois au refresh_token lieu du code. Les jetons d’actualisation sont valides pour toutes les autorisations pour lesquelles votre client a déjà reçu le consentement.

Les jetons d’actualisation n’ont pas de durées de vie spécifiées. En règle générale, les durées de vie des jetons d’actualisation sont relativement longues. Toutefois, dans certains cas, les jetons d’actualisation expirent, sont révoqués ou ne disposent pas de privilèges suffisants pour l’action souhaitée. Votre application doit s’attendre à ce que et gérer correctement les erreurs retournées par le point de terminaison d’émission de jeton. Pour plus d’informations sur les erreurs OAuth, consultez Erreurs OAuth courantes et Codesd’erreur d’authentification et d’autorisation.

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

Le corps de la demande doit inclure les paramètres de la requête et l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded. Définissez le paramètre de jeton d’actualisation sur la valeur du jeton d’actualisation récupéré à l’étape précédente, et le type d’octroi défini sur refresh_token. Si vous avez inscrit une application web, incluez le paramètre client_secret et définissez-le sur la valeur provisionnée dans Inscrire une application.

Le tableau suivant inclut des paramètres que les clients de l’API Bing Ads peuvent inclure dans la demande d’actualisation d’un jeton d’accès. Pour plus d’informations sur les paramètres facultatifs, consultez la documentation sur le flux de code d’autorisation Plateforme d'identités Microsoft OAuth 2.0.

Bien que les jetons d’actualisation ne soient pas révoqués lorsqu’ils sont utilisés pour acquérir de nouveaux jetons d’accès, vous êtes censé ignorer l’ancien jeton d’actualisation. La spécification OAuth 2.0 indique : « Le serveur d’autorisation PEUT émettre un nouveau jeton d’actualisation, auquel cas le client DOIT ignorer l’ancien jeton d’actualisation et le remplacer par le nouveau jeton d’actualisation. Le serveur d’autorisation PEUT révoquer l’ancien jeton d’actualisation après avoir émis un nouveau jeton d’actualisation au client. »

Les jetons d’actualisation sont, et seront toujours, complètement opaques pour votre application. Ils sont de longue durée, par exemple, 90 jours pour les clients publics, mais l’application ne doit pas être écrite pour s’attendre à ce qu’un jeton d’actualisation dure pendant une période quelconque. Les jetons d’actualisation peuvent être invalidés à tout moment, et la seule façon pour une application de savoir si un jeton d’actualisation est valide consiste à tenter de l’utiliser en effectuant une demande de jeton. Même si vous actualisez en permanence le jeton sur le même appareil avec le jeton d’actualisation le plus récent, vous devez vous attendre à recommencer et à demander le consentement de l’utilisateur si, par exemple, l’utilisateur Microsoft Advertising a modifié son mot de passe, supprimé un appareil de sa liste d’appareils approuvés ou supprimé les autorisations permettant à votre application de s’authentifier en son nom. À tout moment, sans avertissement préalable, Microsoft peut déterminer que le consentement de l’utilisateur doit à nouveau être accordé. Dans ce cas, le service d’autorisation retourne une erreur d’octroi non valide, comme indiqué dans l’exemple suivant.

{"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."}

N’oubliez pas que les jetons d’actualisation publics sont uniquement liés à l’appareil accordé. Par exemple, si vous avez inscrit une application native et que vous l’utilisez https://login.microsoftonline.com/common/oauth2/nativeclient comme URI de redirection, nous garantissons uniquement qu’elle peut être actualisée sur le même appareil. Les clients exécutant des applications sur des services qui couvrent des régions et des appareils tels que Microsoft Azure doivent inscrire une application web avec une clé secrète client. L’URI de redirection peut être localhost, mais ne peut pas être https://login.microsoftonline.com/common/oauth2/nativeclient. Si vous utilisez https://login.microsoftonline.com/common/oauth2/nativeclient avec une clé secrète client, l’erreur suivante est retournée.

{"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.

Vous rencontrerez la même erreur si vous essayez de demander de nouveaux jetons d’accès et d’actualisation à l’aide d’un jeton d’actualisation qui a été provisionné sans clé secrète client.

Pour plus d’informations sur les erreurs OAuth, consultez Erreurs OAuth courantes et Codesd’erreur d’authentification et d’autorisation.

Étapes suivantes

Voir aussi

Prise en main