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.

1. Inscrire une application

2. Demander le consentement de l’utilisateur pour que votre application gère ses comptes Microsoft Advertising

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

4. Passer votre premier appel d’API

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.

Vous pouvez suivre ces étapes pour obtenir un jeton de développeur pour la production.

1. Connectez-vous avec les informations d’identification Super Administration sous l’onglet compte du portail des développeurs Microsoft Advertising.
2. 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.
3. 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.

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>

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.

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.

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.

Voir aussi

Vue d’ensemble de l’API Bing Ads
Concepts de l’API Bing Ads