Téléchargement et chargement en bloc

Avec le service en bloc, vous pouvez télécharger et charger les paramètres de campagne de manière asynchrone en arrière-plan. Le service en bloc est recommandé pour la gestion des données à grande échelle, en particulier si vous devez ajouter ou mettre à jour des publicités et des mots clés dans plusieurs groupes d’annonces ou campagnes dans un compte. Pour certaines entités, vous pouvez également télécharger des suggestions d’enchères et des données de score de qualité. Chaque enregistrement peut être chargé correctement, que d’autres enregistrements du même fichier contiennent ou non des erreurs. Pour plus d’informations sur le schéma utilisé pour le téléchargement et le chargement du fichier, notamment sur les entités, les suggestions d’enchères et les données de score de qualité disponibles, consultez Schéma de fichier en bloc.

Si vous utilisez un langage .NET, Java ou Python, vous devez utiliser les bibliothèques clientes d’API Bing Ads. Les SDK .NET, Java et Python abstractionnt des détails de bas niveau décrits ci-dessous. Par exemple, au lieu d’appeler DownloadCampaignsByAccountIds et GetBulkDownloadStatus pour télécharger un fichier, vous pouvez utiliser une méthode avec la classe BulkServiceManager . Pour plus d’informations sur l’utilisation du téléchargement et du chargement en bloc avec les Kits de développement logiciel (SDK), consultez Service Manager en bloc.

Téléchargement en bloc

Pour télécharger les données de campagne d’un compte, appelez l’opération DownloadCampaignsByAccountIds . Pour télécharger les données de campagnes spécifiques, appelez l’opération DownloadCampaignsByCampaignIds .

Téléchargement d’un fichier en bloc

Vous pouvez demander toutes les données de la campagne ou uniquement les données qui ont changé depuis la dernière fois que vous avez téléchargé les données de la campagne. Pour l’une ou l’autre opération de téléchargement, voici une vue d’ensemble des paramètres de requête et du flux de travail de téléchargement.

1. Définissez l’élément DataScope de la demande et spécifiez s’il faut inclure des suggestions d’enchères ou des données de score de qualité en plus des données d’entité. Pour obtenir la liste des valeurs possibles, consultez l’ensemble de valeurs DataScope .

2. Définissez l’élément DownloadFileType de la demande pour sélectionner csv ou Tsv pour le format du fichier de téléchargement.

   Remarque

   Le fichier CSV ou Tsv téléchargé sera compressé zip ou GZIP en fonction du type de compression que vous avez spécifié. ZIP est la valeur par défaut si vous n’avez pas spécifié CompressionType.

3. Définissez l’élément Entities de la demande pour inclure vos entités de campagne, de groupe d’annonces, d’annonces et de mot clé. Vous pouvez éventuellement inclure des entités supplémentaires telles que des mots clés négatifs et des cibles dans le téléchargement. Pour obtenir la liste des entités que vous pouvez demander, consultez l’ensemble de valeurs DownloadEntity .

4. Définissez l’élément LastSyncTimeInUTC de la demande sur l’horodatage du téléchargement précédent pour demander uniquement les entités qui ont été mises à jour ou supprimées depuis le dernier téléchargement.

   Remarque

   S’il s’agit de la première fois que vous demandez un téléchargement pour les entités spécifiées, définissez l’élément LastSyncTimeInUTC de la demande sur NULL pour télécharger toutes les entités disponibles.

5. Envoyez la demande de téléchargement avec l’opération DownloadCampaignsByAccountIds ou DownloadCampaignsByCampaignIds .

6. La demande de téléchargement retourne un identificateur que vous passez à l’opération GetBulkDownloadStatus . Vous appelez l’opération GetBulkDownloadStatus dans une boucle jusqu’à ce que le téléchargement se termine ou échoue. La durée du téléchargement dépend d’un certain nombre de variables, telles que le nombre de campagnes que vous avez demandées et le nombre de demandes déjà dans la file d’attente. En raison de ces variables, l’intervalle d’interrogation que vous utilisez peut varier. Vous avez deux jours pour télécharger le fichier à partir du moment où vous envoyez la demande de téléchargement. Si vous n’avez pas téléchargé le fichier au cours de cette période, il est supprimé du site de téléchargement et vous devrez appeler à nouveau l’une des opérations de téléchargement.

7. Une fois l’opération GetBulkDownloadStatus terminée, elle retourne l’URL du fichier de téléchargement. Utilisez l’URL pour copier le fichier de téléchargement localement. L’URL doit être utilisée dans les cinq minutes suivant le moment où l’opération GetBulkDownloadStatus retourne un code success status. Si vous ne démarrez pas le téléchargement pendant cette période, vous devez appeler à nouveau GetBulkDownloadStatus pour obtenir une nouvelle URL.

8. Le fichier de téléchargement étant compressé au format zip, vous devez décompresser le fichier pour accéder aux données. Pour plus d’informations sur le schéma utilisé pour le fichier de téléchargement, consultez Schéma de fichier en bloc.

Télécharger les meilleures pratiques

Respectez les bonnes pratiques pour garantir une utilisation équitable pour vous et tous les clients Microsoft Advertising.

• Demandez uniquement les entités de téléchargement en bloc dont vous avez besoin. Les nouveaux types d’enregistrements (lignes) et les champs (colonnes) peuvent être ajoutés à tout moment, et vous ne devez pas dépendre de l’enregistrement ou de l’ordre des champs dans le fichier de résultats de téléchargement en bloc ou de chargement en bloc.

• Effectuez un téléchargement complet une seule fois. Ensuite, effectuez des téléchargements delta. Définissez LastSyncTimeInUTC sur l’horodatage du dernier téléchargement. Le fichier de téléchargement contient l’horodatage du téléchargement dans la colonne SyncTime de l’enregistrement de compte . Il n’y a aucun avantage à effectuer un téléchargement complet à chaque fois et cela diminue les performances de tout le monde, y compris les vôtres.

• Interrogez les téléchargements à intervalles raisonnables. Vous connaissez vos données mieux que quiconque. Si vous téléchargez un compte qui est bien inférieur à un million de mots clés, envisagez d’interroger à intervalles de 15 à 20 secondes. Si le compte contient environ un million de mots clés, envisagez d’interroger à intervalles d’une minute après cinq minutes d’attente. Pour les comptes avec environ quatre millions de mots clés, envisagez d’interroger à intervalles d’une minute après 10 minutes d’attente.

• Appelez l’opération DownloadCampaignsByCampaignIds si le compte contient plus de quatre millions de mots clés. L’appel de l’opération DownloadCampaignsByAccountIds avec un compte contenant plus de quatre millions de mots clés échoue.

• Vous pouvez inclure moins de campagnes dans votre demande DownloadCampaignsByCampaignIds . L’appel de l’opération DownloadCampaignsByCampaignIds avec un compte contenant plus de huit millions de mots clés échoue. Les demandes qui spécifient moins de campagnes par appel se terminent généralement plus tôt que les appels qui spécifient le nombre maximal autorisé.

Chargement en bloc

Vous pouvez envoyer votre fichier de chargement en bloc avec HTTP POST à une URL fournie par le service en bloc.

Pour plus d’informations sur le schéma que vous devez utiliser pour le fichier de chargement, consultez Schéma de fichier en bloc.

Chargement d’un fichier en bloc

Voici une vue d’ensemble des paramètres de requête et du flux de travail de chargement.

1. Définissez l’élément AccountId de la requête GetBulkUploadUrl sur l’identificateur de compte correspondant aux données qui seront chargées.

2. Définissez l’élément ResponseMode de la requête GetBulkUploadUrl pour spécifier si le service doit retourner les erreurs et leurs données correspondantes, ou uniquement les erreurs dans le fichier de résultats. Pour plus d’informations, consultez ResponseMode.

3. Utilisez le UploadUrl retourné avec la réponse GetBulkUploadUrl pour envoyer votre fichier de chargement en bloc avec HTTP POST. Le type de contenu doit être multipart/form-data. Les fichiers UTF-8 doivent inclure la marque d’ordre d’octet (BOM). Le chargement compressé zip doit contenir un fichier au format Csv ou Tsv. Le fichier ZIP doit être correctement structuré, y compris une fin d’enregistrement de répertoire central.

   Remarque

   L’en-tête d’autorisation http standard n’est pas utilisé. Pour vous authentifier, vous devez ajouter et définir les éléments d’en-tête personnalisés Microsoft Advertising de votre client HTTP, notamment les en-têtes DeveloperToken, CustomerId et CustomerAccountId . Vous devez également définir les informations d’identification de l’utilisateur via l’élément d’en-tête AuthenticationToken . Pour plus d’informations, consultez Authentification avec OAuth et Où utiliser les informations d’identification de l’API.

   Vous devez utiliser les mêmes informations d’identification utilisateur dans le flux de travail GetBulkUploadUrl, HTTP POST et GetBulkUploadStatus .

   Voici un exemple.

   POST <UploadUrl> HTTP/1.1
   AuthenticationToken: <AuthenticationToken>
   DeveloperToken: <DeveloperToken>
   CustomerId: <CustomerId>
   AccountId: <AccountId>
   Content-Type: multipart/form-data;
   

4. Vérifiez le code de status de réponse HTTP. Si la réponse HTTP status code est 200, le fichier a été reçu avec succès par Microsoft Advertising. Si la réponse HTTP status code est 401, l’authentification a échoué, par exemple AuthenticationToken ou DeveloperToken n’était pas valide. Si le code de status de réponse HTTP est 400, vous devez également case activée le flux de réponse pour les codes d’erreur d’opération de l’API Bing Ads, par exemple, dans la plage de 3220 à 3227.

   Voici un exemple de message de réponse d’erreur indiquant que l’URL a déjà été utilisée pour charger un fichier en bloc.

   HTTP/1.1 400 Bad Request
   Cache-Control: private
   Content-Type: application/json; charset=utf-8
   Server: Microsoft-IIS/8.0
   X-AspNetMvc-Version: 3.0
   X-AspNet-Version: 4.0.30319
   X-Powered-By: ASP.NET
   Date: Tue, 12 Jan 2016 17:07:23 GMT
   Content-Length: 224
   
   {"TrackingId":"16bd93cc-22fb-4d3c-94be-25adefd06fae","RequestId":"26c3fbf6-3e24-4569-ada3-d4e8b3d0aecc","Code":3224,"ErrorCode":"BulkServiceUrlAlreadyUsedForUpload","Message":"The URL has already been used for file upload."}
   

5. La réponse GetBulkUploadUrl inclut également un RequestId que vous passez à l’opération GetBulkUploadStatus . Pendant que le chargement est en attente, vous pouvez appeler l’opération GetBulkUploadStatus dans une boucle jusqu’à ce que le chargement se termine ou échoue. Vous avez quinze minutes pour télécharger le fichier de résultats de chargement à partir du moment où vous envoyez la demande de chargement. Si vous n’avez pas correctement téléchargé le fichier au cours de cette période, il est supprimé du site de téléchargement et il est possible qu’il ne soit pas récupéré. Si vous manquez cette fenêtre d’opportunité, vous pouvez appeler l’une des opérations de téléchargement pour obtenir les données d’entité les plus récentes.

6. Une fois l’opération GetBulkUploadStatus terminée, elle retourne l’URL du fichier de résultats de chargement. Utilisez l’URL pour copier le fichier de résultats localement. L’URL doit être utilisée dans les quinze minutes suivant le moment où l’opération GetBulkUploadStatus retourne la chaîne de réponse Completed status. Si vous ne démarrez pas le téléchargement dans ce délai, vous devez appeler à nouveau GetBulkUploadStatus pour obtenir une nouvelle URL.

   Remarque

   Le format du fichier de résultat de chargement sera Csv ou Tsv et correspondra au format du fichier que vous avez envoyé pour le chargement.

Meilleures pratiques de chargement

Respectez les bonnes pratiques pour garantir une utilisation équitable pour vous et tous les clients Microsoft Advertising.

• Les fichiers volumineux peuvent dégrader les performances de chargement. Il est facultatif et recommandé de compresser le fichier pour le chargement. S’il est compressé, il doit être au format ZIP avec l’extension correspondante. La limite de taille de fichier pour le chargement en production est de 100 Mo et jusqu’à 4 millions de lignes. Pour le bac à sable , la limite est de 20 000 lignes. Si vous pouvez limiter les chargements simultanés par client en dessous de 5 ou 6, envisagez de fractionner le fichier plutôt que de s’approcher de la limite de taille de fichier.

• Limitez les chargements simultanés à 5 ou 6 par client pour charger des fichiers en parallèle. Patientez sur chaque thread jusqu’à ce que le fichier précédent ait été traité, puis vous pouvez réutiliser le thread pour charger un autre fichier. Par exemple, un thread peut charger un fichier et une fois que le status de chargement est Terminé, CompletedWithErrors ou Failed, ce thread peut charger un autre fichier.

• Chargez uniquement les entités et les champs que vous ajoutez ou mettez à jour. S’ils sont fournis, les champs en lecture seule tels que les suggestions d’enchères et les données de score de qualité sont ignorés.

• Chargez un type d’entité par fichier pour optimiser les performances. Il existe quelques exceptions, par exemple, lors de la création de campagnes, de publicités et de mots clés, il peut être plus efficace de les charger avec des clés de référence. Autre exemple, si vous ne mettez à jour que 10 campagnes, 500 annonces et 800 mots clés, vous pouvez les inclure dans un seul chargement au lieu de fractionner les chargements par type.

• Déterminez si vous devez demander des erreurs et des résultats (ResponseMode = ErrorsAndResults) dans le fichier de résultats de chargement, ou si seules les erreurs (ResponseMode = ErrorsOnly) suffiront. Déterminez si vous devez synchroniser les résultats avec vos données locales. Par exemple, si vous mettez à jour des entités, vous devrez peut-être uniquement savoir si des erreurs se sont produites et, dans ce cas, vous pouvez spécifier ResponseMode = ErrorsOnly dans la requête GetBulkUploadUrl . Si vous ajoutez de nouvelles entités, vous pouvez spécifier ResponseMode = ErrorsAndResults dans la requête GetBulkUploadUrl pour recevoir les identificateurs d’entité résultants.

• Pour les nouvelles tentatives partielles, ne chargez pas le fichier entier si seul un sous-ensemble des enregistrements a entraîné des erreurs. Chargez uniquement les enregistrements que vous souhaitez réessayer.

• Ne réessayez pas tant que le chargement status n’est pas Terminé, CompletedWithErrors ou Failed. Si, par hasard, les performances ne répondent pas aux attentes, veuillez quand même attendre le résultat.

• Interrogez les résultats du chargement à intervalles raisonnables. Au départ, vous devez attendre une minute pour chaque 10 000 lignes chargées. Après le temps d’attente initial, envisagez d’interroger par intervalles d’une minute.

Voir aussi

Informations de référence sur le service en bloc
Adresses du service web de l’API Bing Ads