Protocole des services d’API Bing Ads

Vous pouvez écrire votre application API Bing Ads dans n’importe quelle langue prenant en charge les services web. Un document WSDL (Web Services Description Language) est défini pour chaque service web. Le WSDL définit les opérations qu’un service web offre et le format des messages de demande et de réponse que le client envoie et reçoit des opérations. Les messages de demande et de réponse définissent les noms et les types des données que le client échange avec l’opération. Pour plus d’informations sur les WSDL, consultez la spécification W3C WSDL.

SOAP pour l’API Bing Ads

L’API Bing Ads prend en charge le protocole SOAP (Simple Object Access Protocol). Certains langages, tels que C# et Java, fournissent des outils qui génèrent des classes proxy à partir du WSDL. Si la langue de votre choix ne fournit pas d’outil pour générer des classes proxy, vous devez générer vos propres classes proxy ou enveloppes SOAP. Pour générer les classes proxy, vous avez besoin de l’adresse web du document WSDL du service que vous souhaitez utiliser. Le bac à sable Microsoft Advertising et les environnements de production ont chacun une adresse unique. Les adresses incluent également le numéro de version du WSDL spécifique à une version majeure de l’API Bing Ads. Pour les WSDL de service de production et de bac à sable de la dernière version de l’API Bing Ads, consultez Adresses du service web de l’API Bing Ads.

Ordre des éléments XML SOAP

Lorsque vous créez un message de requête SOAP, l’ordre des éléments dans le corps SOAP est critique. Les éléments doivent être dans le même ordre que celui défini dans le langage WSDL (Web Services Description Language). Si les éléments requis sont dans le désordre, l’appel échoue. Si les éléments facultatifs sont dans le désordre, l’appel peut échouer ou les éléments sont ignorés. La syntaxe WSDL, qui montre l’ordre correct des éléments, est incluse avec chaque message de demande, message de réponse et objet de données documenté dans le contenu de référence. En outre, chaque message de demande et de réponse affiche un exemple d’enveloppe SOAP.

Remarque

XML respecte la casse. Vous devez utiliser la casse correcte pour les noms de valeurs. Les langages de programmation fortement typés tels que C# garantissent que vous disposez de la casse correcte avant de pouvoir compiler. D’autres langues peuvent ne pas vous donner une erreur de compilation si le cas correct n’est pas utilisé ; toutefois, le code échoue au moment de l’exécution.

Réussite partielle

L’API Bing Ads prend en charge les complétions partielles pour les opérations d’ajout, de mise à jour et de suppression ; Si l’un des objets de la liste des objets que vous ajoutez, mettez à jour ou supprimez échoue, l’opération peut réussir pour d’autres personnes de la collection. Lorsque vous appelez une opération Get qui prend une liste d’identificateurs, par exemple, l’opération GetKeywordsByIds , et que l’un des identificateurs de la liste n’est pas valide, l’opération réussit et l’élément response qui correspond à l’identificateur de requête non valide est nul.

Mise à jour partielle

Mise à jour partielle de la gestion des campagnes

La mise à jour partielle est prise en charge pour la plupart des objets de données de gestion des campagnes, mais pas tous. Par exemple, lors de la mise à jour de la propriété Text d’un ExpandedTextAd , vous devez uniquement spécifier les éléments Id et Text . Les éléments en lecture seule tels que la status éditoriale de l’annonce doivent être laissés à zéro ou vides. Sauf indication contraire explicite, les éléments facultatifs peuvent être laissés vides et leurs paramètres existants restent inchangés.

La mise à jour partielle n’est pas prise en charge pour les extensions publicitaires. Tous les éléments facultatifs qui ne sont pas envoyés avec la demande de mise à jour sont en effet supprimés de l’extension publicitaire correspondante.

Mise à jour partielle de la gestion des clients

Le service de gestion des clients effectue une mise à jour complète des entités. Par conséquent, en plus des propriétés requises documentées, vous devez fournir des valeurs pour toutes les propriétés facultatives que vous ne souhaitez pas être nulles ou vides.

Remarque

L’élément ForwardCompatibilityMap de tout objet constitue une exception à cette règle. Par exemple, si vous ne fournissez pas l’élément ForwardCompatibilityMap de l’objet AdvertiserAccount, le service ne met pas à jour ou nullifie les propriétés qui auraient autrement été représentées par des paires clé et valeur.

Stocker vos identificateurs d’entité localement

Vous devez gérer un magasin local des entités de votre compte et de votre campagne. Plus précisément, vous devez stocker localement les identificateurs de vos comptes, clients, campagnes, groupes d’annonces et mots clés. La plupart des appels nécessitent l’identificateur de l’entité. Si vous stockez l’identificateur, vous éliminez l’appel requis pour obtenir l’identificateur.

Par exemple, la plupart des appels de gestion de campagne nécessitent un identificateur de compte. Pour obtenir l’identificateur de compte, vous pouvez utiliser le service de gestion des clients. Toutefois, au lieu d’appeler le service à plusieurs reprises, stockez l’identificateur de compte localement afin de pouvoir l’utiliser dans les appels suivants.

Gérer la surcharge associée à la réalisation d’appels de service web

Voici les coûts généraux associés à chaque appel de service web, en temps de traitement.

• Établissement d’une connexion HTTPS au service web.
• Authentification du nom d’utilisateur et du mot de passe.
• Validation du jeton de développeur.

Ces coûts se produisent si vous traitez un seul élément ou un ensemble d’éléments. Pour réduire la surcharge, en général, vous devez essayer de traiter autant d’éléments que possible dans un seul appel. Par exemple, au lieu d’appeler UpdateCampaigns pour chaque campagne que vous souhaitez mettre à jour, appelez-la une seule fois pour plusieurs campagnes que vous souhaitez mettre à jour. Pour gérer des données à grande échelle, en particulier si vous avez besoin d’ajouter ou de mettre à jour des annonces et des mots clés dans plusieurs groupes ou campagnes publicitaires dans un compte, vous devez utiliser le service en bloc. Le service en bloc vous permet de télécharger des données sous forme de fichier TSV ou CSV, de les modifier en fonction des besoins, puis de charger vos modifications. Pour plus d’informations sur l’utilisation du service en bloc, consultez Téléchargement et chargement en bloc.

En raison des coûts associés à l’établissement d’une connexion à un service web, vous devez maintenir la connexion aussi longtemps que nécessaire. Par exemple, si vous avez besoin de demander plusieurs rapports, utilisez le même objet client du service de création de rapports pour tous les appels d’opérations de service de création de rapports. Fermez explicitement la connexion lorsque vous n’avez plus besoin du service.

Gérer la limitation

La limitation de l’utilisation à très haut volume maintient une utilisation équitable pour tous les clients Microsoft Advertising.

Ad Insight API

Pour le service Ad Insight, la limitation limite le nombre d’appels à l’API que tout utilisateur peut effectuer en une minute.

Au niveau du client, le nombre d’appels qu’un client peut effectuer pour les données client est limité à l’aide d’un protocole glissant avec une fenêtre de 60 secondes.

Si vous dépassez la limite des appels de service, l’erreur suivante s’affiche :

• Code d’erreur numérique : 117
• Code d’erreur symbolique : CallRateExceeded
• Message : Vous avez dépassé le nombre d’appels que vous êtes autorisé à effectuer en une minute. Veuillez réduire le nombre d’appels que vous effectuez par minute.

Lorsque vous observez cette erreur, vous pouvez soumettre à nouveau la requête sous la limite après 60 secondes d’attente.

API en bloc

Le service en bloc limite le nombre de demandes que vous pouvez effectuer à DownloadCampaignsByAccountIds, DownloadCampaignsByCampaignIds et GetBulkUploadUrl. Les détails des limites de service sont internes et susceptibles d’être modifiés.

Si vous atteignez la limite d’appels de service, l’erreur suivante s’affiche :

• Code d’erreur numérique : 4204
• Code d’erreur symbolique : BulkServiceNoMoreCallsPermittedForTheTimePeriod
• Message : Aucun autre chargement ou téléchargement en bloc n’est autorisé pour ce compte pendant la période actuelle. Si vous avez atteint votre limite de chargement en bloc, les opérations de téléchargement en bloc peuvent toujours être disponibles, ou vice versa.

Si vous observez cette erreur, vous pouvez soumettre à nouveau votre demande après avoir attendu jusqu’à 15 minutes. Pour plus d’informations, consultez Meilleures pratiques de téléchargement en bloc et Meilleures pratiques de chargement en bloc.

Notez également que la limite de taille par fichier pour le chargement en bloc en production est de 100 Mo et jusqu’à 4 millions de lignes. Pour le bac à sable , la limite est de 20 000 lignes.

API de gestion des campagnes

Pour le service Campaign Management, la limitation limite le nombre d’appels à l’API que n’importe quel utilisateur peut effectuer en une minute.

Au niveau du client, le nombre d’appels qu’un client peut effectuer pour les données client est limité à l’aide d’un protocole glissant avec une fenêtre de 60 secondes.

Si vous atteignez la limite d’appels de service, l’erreur suivante s’affiche :

• Code d’erreur numérique : 117
• Code d’erreur symbolique : CallRateExceeded
• Message : Vous avez dépassé le nombre d’appels que vous êtes autorisé à effectuer en une minute. Veuillez réduire le nombre d’appels que vous effectuez par minute.

Lorsque vous observez cette erreur, vous pouvez soumettre à nouveau la requête sous la limite après 60 secondes d’attente.

API de création de rapports

Le service Reporting limite le nombre de demandes que vous pouvez effectuer à SubmitGenerateReportRequest. Les détails des limites de service sont internes et susceptibles d’être modifiés.

Si vous atteignez la limite d’appels de service, l’erreur suivante s’affiche :

• Code d’erreur numérique : 207
• Code d’erreur symbolique : ConcurrentRequestOverLimit
• Message : Vous avez déjà atteint le nombre maximal de demandes de rapport simultanées. Attendez que les rapports précédents soient terminés, puis essayez d’envoyer une nouvelle demande.

Si vous observez cette erreur, attendez que les rapports précédents soient terminés, puis essayez d’envoyer une nouvelle demande.

Voir aussi

Adresses du service web de l’API Bing Ads
Vue d’ensemble de l’API Bing Ads