Prise en main de l’API Bing Ads
Tout utilisateur Microsoft Advertising disposant d’un jeton de développeur peut commencer à utiliser l’API Bing Ads. Pour les annonceurs qui placent un grand nombre de publicités ou de développeurs qui créent des outils publicitaires, l’API Bing Ads fournit une interface de programmation à Microsoft Advertising.
Vous pouvez développer votre application API Bing Ads dans n’importe quelle langue prenant en charge les services web. Pour bien démarrer avec un KIT de développement logiciel (SDK) spécifique, consultez Prise en main de C# | Java | PHP | Python.
Obtenir un jeton d’accès utilisateur
Considérez l’utilisateur que vous souhaitez connecter, par exemple. example@contoso.com L’API Bing Ads n’accepte pas cette adresse e-mail et ce mot de passe. Au lieu de cela, vous devez définir l’élément d’en-tête AuthenticationToken qui contient un jeton d’accès utilisateur. Vous pouvez considérer un jeton d’accès comme représentant un nom d’utilisateur et un mot de passe.
Comment obtenir un jeton d’accès pour un utilisateur ? En tant que développeur d’applications, vous allez utiliser une URL d’autorisation Microsoft pour inviter l’utilisateur Microsoft Advertising à donner son consentement. Une fois qu’un utilisateur a donné son consentement, vous pouvez obtenir un jeton d’accès et agir au nom de l’utilisateur. Le jeton d’accès représente les informations d’identification de l’utilisateur qui a accès à un ou plusieurs comptes Microsoft Advertising.
Demander le consentement de l’utilisateur pour que votre application gère ses comptes Microsoft Advertising
Conseil
Pour plus d’informations sur la façon d’obtenir des jetons d’accès et d’actualisation à l’aide des Kits de développement logiciel (SDK) Bing Ads, consultez Authentification avec les KITS de développement logiciel (SDK).
Obtenir un jeton de développeur
Pour utiliser les API Bing Ads, vous devez disposer d’un jeton de développeur et d’informations d’identification utilisateur valides. Si vous n’avez pas encore de compte Microsoft Advertising, vous pouvez vous inscrire via l’application web Microsoft Advertising.
Remarque
Les environnements de bac à sable et de production utilisent des informations d’identification distinctes. Vous pouvez vous inscrire pour obtenir un compte de bac à sableici. Tout le monde peut utiliser le jeton de développeur de bac à sable universel, c’est-à-dire BBD37VB98.
Vous pouvez suivre ces étapes pour obtenir un jeton de développeur pour la production.
- Connectez-vous avec les informations d’identification Super Administration sous l’onglet compte du portail des développeurs Microsoft Advertising.
- Choisissez l’utilisateur que vous souhaitez associer au jeton de développeur. En règle générale, une application n’a besoin que d’un seul jeton universel, quel que soit le nombre d’utilisateurs pris en charge.
- Cliquez sur le bouton Demander un jeton .
Le jeton de développeur universel peut être utilisé pour s’authentifier avec les informations d’identification de l’utilisateur Microsoft Advertising. Vous pouvez utiliser le même jeton de développeur universel, que votre application soit utilisée par un ou plusieurs utilisateurs de Microsoft Advertising. Depuis juillet 2019, il s’agit du type de jeton par défaut.
Le jeton de développeur mono-utilisateur ne peut être utilisé que pour authentifier un utilisateur pour l’accès à un seul client. Ce type de jeton a été déprécié en faveur du jeton universel. Si vous voyez toujours qu’un seul jeton d’utilisateur est affecté à l’un de vos utilisateurs, vous pouvez sélectionner « Mettre à niveau vers universal ».
Un jeton de développeur permet d’accéder par programmation aux comptes autorisés pour un utilisateur. L’obtention d’un jeton de développeur pour l’accès à l’API n’accorde pas d’autorisations supplémentaires aux comptes Microsoft Advertising. Chaque utilisateur Microsoft Advertising se voit attribuer un rôle, par exemple, Super Administration ou Responsable de campagne de l’annonceur pour chaque client auquel il peut accéder. Avec un jeton de développeur, les mêmes comptes disponibles dans l’application web Microsoft Advertising sont disponibles pour l’utilisateur par programmation via l’API.
Où utiliser les informations d’identification de l’API
Lorsque vous appelez une opération de service telle que GetCampaignsByAccountId, vous devez spécifier des éléments d’en-tête de requête tels que DeveloperToken, CustomerId et CustomerAccountId.
<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<Action mustUnderstand="1">GetCampaignsByAccountId</Action>
<ApplicationToken i:nil="false">ValueHere</ApplicationToken>
<AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
<CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
<CustomerId i:nil="false">ValueHere</CustomerId>
<DeveloperToken i:nil="false">ValueHere</DeveloperToken>
</s:Header>
<s:Body>
<GetCampaignsByAccountIdRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<AccountId>ValueHere</AccountId>
<CampaignType>ValueHere</CampaignType>
</GetCampaignsByAccountIdRequest>
</s:Body>
</s:Envelope>
Si vous utilisez l’un des Kits de développement logiciel (SDK) Microsoft Advertising, les éléments d’en-tête de requête sont définis à l’aide d’AuthorizationData. Pour plus d’informations sur la bibliothèque d’authentification du SDK, consultez Authentification avec les KITS de développement logiciel (SDK).
var authorizationData = new AuthorizationData
{
Authentication = <AuthenticationGoesHere>,
CustomerId = <CustomerIdGoesHere>,
AccountId = <AccountIdGoesHere>,
DeveloperToken = "<DeveloperTokenGoesHere>"
};
static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");
$authorizationData = (new AuthorizationData())
->withAuthentication($AuthenticationGoesHere)
->withCustomerId($CustomerIdGoesHere)
->withAccountId($AccountIdGoesHere)
->withDeveloperToken($DeveloperTokenGoesHere);
authorization_data = AuthorizationData(
authentication = <AuthenticationGoesHere>,
customer_id = <CustomerIdGoesHere>,
account_id = <AccountIdGoesHere>,
developer_token = '<DeveloperTokenGoesHere>'
)
Obtenir vos ID de compte et de client
Pour obtenir l’ID client et l’ID de compte d’un utilisateur, vous pouvez vous connecter à l’application web Microsoft Advertising et cliquer sur l’onglet Campagnes . L’URL contient une paire clé/valeur cid dans la chaîne de requête qui identifie votre ID client, et une paire clé/valeur d’aide qui identifie votre ID de compte. Par exemple, https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere& aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign.
Conseil
Ne confondez pas le numéro de compte avec l’identificateur du compte. Le numéro de compte est le numéro de compte généré par le système qui est utilisé pour identifier le compte dans l’application web Microsoft Advertising. Le numéro de compte a la forme xxxxxxxx, où xxxxxxxx est une série de huit caractères alphanumériques. Les demandes du service API utilisent uniquement l’identificateur de compte et n’utilisent jamais le numéro de compte.
Avec l’API Gestion des clients, vous pouvez obtenir les identificateurs de client et de compte pour chaque utilisateur authentifié.
Appelez GetUser avec vos informations d’identification Microsoft Advertising et DeveloperToken. Dans le corps, définissez l’Id utilisateur zéro. La réponse inclut un objet User qui contient l’UserId.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
<h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
</s:Header>
<s:Body>
<GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
<UserId i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
</GetUserRequest>
</s:Body>
</s:Envelope>
Appelez ensuite SearchAccounts avec l’Id d’utilisateur retourné à l’étape précédente. Le ou les comptes d’annonceur retournés incluent les identificateurs de compte et de client.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
<h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
</s:Header>
<s:Body>
<SearchAccountsRequest xmlns="https://bingads.microsoft.com/Customer/v13">
<Predicates xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Predicate>
<a:Field>UserId</a:Field>
<a:Operator>Equals</a:Operator>
<a:Value>UserIdGoesHere</a:Value>
</a:Predicate>
</Predicates>
<Ordering i:nil="true" xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
<PageInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:Index>0</a:Index>
<a:Size>10</a:Size>
</PageInfo>
</SearchAccountsRequest>
</s:Body>
</s:Envelope>
Conseil
Consultez Exemple de code de recherche de comptes d’utilisateur pour obtenir un exemple de code qui retourne des comptes pour l’utilisateur authentifié actuel.
Informations de référence sur les éléments d’en-tête
Les opérations du service API Bing Ads utilisent le protocole SOAP (Simple Object Access Protocol) pour échanger les messages de demande et de réponse avec l’opération de service. Pour plus d’informations, consultez Protocole des services d’API Bing Ads.
Chaque requête SOAP doit inclure les en-têtes SOAP suivants, qui contiennent les informations d’identification de l’utilisateur.
Remarque
Les éléments CustomerAccountId et CustomerId ne s’appliquent pas aux services Customer Billing et Customer Management.
| Élément | Description | Type de données |
|---|---|---|
| ApplicationToken | Cet élément d’en-tête n’est pas utilisé et doit être ignoré. | chaîne |
| AuthenticationToken | Jeton d’accès OAuth qui représente un utilisateur de compte Microsoft disposant d’autorisations sur des comptes Microsoft Advertising. Pour plus d’informations, consultez Authentification avec OAuth. | chaîne |
| CustomerAccountId | Identificateur du compte propriétaire des entités dans la demande. Cet élément d’en-tête doit avoir la même valeur que l’élément de corps AccountId lorsque les deux sont nécessaires. Cet élément est requis pour la plupart des opérations de service et, à titre de bonne pratique, vous devez toujours le définir. | chaîne |
| Customerid | Identificateur du client qui contient et possède le compte. Si vous gérez un compte d’un autre client, vous devez utiliser cet ID client au lieu de votre propre ID client. Cet élément est requis pour la plupart des opérations de service et, à titre de bonne pratique, vous devez toujours le définir. | chaîne |
| DeveloperToken | Jeton de développeur utilisé pour accéder à l’API Bing Ads. | chaîne |
| Mot de passe | Cet élément est réservé à un usage interne et sera supprimé d’une version ultérieure de l’API. Vous devez utiliser l’élément AuthenticationToken pour définir les informations d’identification de l’utilisateur. | chaîne |
| UserName | Cet élément est réservé à un usage interne et sera supprimé d’une version ultérieure de l’API. Vous devez utiliser l’élément AuthenticationToken pour définir les informations d’identification de l’utilisateur. | chaîne |
Besoin d’aide ?
Pour obtenir des conseils de dépannage, consultez Gestion des erreurs et exceptions de service.
Le forum Microsoft Q&A est accessible à la communauté des développeurs pour poser des questions et y répondre sur les API Bing Ads et les scripts Microsoft Advertising. Microsoft surveille les forums et répond aux questions auxquelles la communauté n’a pas encore répondu.
Importante
Pour vous assurer que nous voyons votre question, étiquetez-la avec « advertising-api ».
Si l’enquête implique des informations personnelles ou de compte sensibles, ou si vous ne trouvez pas les informations dont vous avez besoin pour résoudre votre problème via Microsoft Q&R, contactez le support Microsoft Advertising. Pour résoudre le problème efficacement, fournissez le support avec les détails demandés dans Engagement de support.