Freigeben über

Massendownload und -upload

  • Artikel

Mit dem Massendienst können Sie Kampagneneinstellungen asynchron im Hintergrund herunterladen und hochladen. Der Massendienst wird für die Verwaltung umfangreicher Daten empfohlen, insbesondere wenn Sie Anzeigen und Schlüsselwörter in mehreren Anzeigengruppen oder Kampagnen in einem Konto hinzufügen oder aktualisieren müssen. Für einige Entitäten können Sie auch Gebotsvorschläge und Qualitätsbewertungsdaten herunterladen. Jeder Datensatz kann erfolgreich hochgeladen werden, unabhängig davon, ob andere Datensätze in derselben Datei Fehler enthalten. Informationen zum Schema, das für das Herunterladen und Hochladen der Datei verwendet wird, einschließlich Details dazu, welche Entitäten, Gebotsvorschläge und Qualitätsbewertungsdaten verfügbar sind, finden Sie unter Massendateischema.

Wichtig

Neue Datensatztypen (Zeilen) und Felder (Spalten) können jederzeit hinzugefügt werden, und Sie sollten sich nicht auf die Datensatz- oder Feldreihenfolge in der Massendownload- oder Massenupload-Ergebnisdatei verlassen. Ebenso sollten Sie, sofern in der Referenzdokumentation nicht anders angegeben, nicht von einem festen Satz von Werten abhängig sein, die in jedem Feld zurückgegeben werden.

Wenn Sie eine .NET-Sprache, Java oder Python verwenden, sollten Sie die Clientbibliotheken der Bing Ads-API verwenden. Die .NET-, Java- und Python-SDKs abstrahen die unten beschriebenen Details auf niedriger Ebene. Anstatt beispielsweise DownloadCampaignsByAccountIds und GetBulkDownloadStatus zum Herunterladen einer Datei aufzurufen, können Sie eine Methode mit der BulkServiceManager-Klasse verwenden. Weitere Informationen zur Verwendung des Massendownloads und -uploads mit den SDKs finden Sie unter Bulk Service Manager.

Massendownload

Rufen Sie zum Herunterladen der Kampagnendaten eines Kontos den Vorgang DownloadCampaignsByAccountIds auf. Um die Daten bestimmter Kampagnen herunterzuladen, rufen Sie den Vorgang DownloadCampaignsByCampaignIds auf.

Herunterladen einer Massendatei

Sie können alle Daten der Kampagne oder nur die Daten anfordern, die sich seit dem letzten Herunterladen der Kampagnendaten geändert haben. Für beide Downloadvorgänge gibt es eine Übersicht über die Anforderungseinstellungen und den Downloadworkflow.

Wichtig

Sie müssen die gleichen Benutzeranmeldeinformationen für den Downloadanforderungsvorgang (entweder DownloadCampaignsByAccountIds oder DownloadCampaignsByCampaignIds) und den GetBulkDownloadStatus-Abrufvorgang verwenden.

  1. Legen Sie das DataScope-Element der Anforderung fest, und geben Sie an, ob zusätzlich zu Entitätsdaten Gebotsvorschläge oder Qualitätsbewertungsdaten eingeschlossen werden sollen. Eine Liste der möglichen Werte finden Sie im DataScope-Wertsatz .

  2. Legen Sie das DownloadFileType-Element der Anforderung fest, um csv odertsv für das Format der Downloaddatei auszuwählen.

    Hinweis

    Die heruntergeladene CSV- oder Tsv-Datei wird je nach angegebenem CompressionType entweder ZIP oder GZIP komprimiert. ZIP ist die Standardeinstellung, wenn Sie CompressionType nicht angegeben haben.

  3. Legen Sie das Entities-Element der Anforderung so fest, dass Ihre Kampagnen-, Anzeigengruppen-, Anzeigen- und Schlüsselwort (keyword)-Entitäten eingeschlossen werden. Optional können Sie zusätzliche Entitäten wie negative Schlüsselwörter und Ziele in den Download einschließen. Eine Liste der Entitäten, die Sie anfordern können, finden Sie unter DownloadEntity-Wertsatz .

  4. Legen Sie das LastSyncTimeInUTC-Element der Anforderung auf den Zeitstempel des vorherigen Downloads fest, um nur die Entitäten anzufordern, die seit dem letzten Download aktualisiert oder gelöscht wurden.

    Hinweis

    Wenn Sie zum ersten Mal einen Download für die angegebenen Entitäten anfordern, legen Sie das LastSyncTimeInUTC-Element der Anforderung auf NULL fest, um alle verfügbaren Entitäten herunterzuladen.

  5. Übermitteln Sie die Downloadanforderung entweder mit dem Vorgang DownloadCampaignsByAccountIds oder DownloadCampaignsByCampaignIds .

  6. Die Downloadanforderung gibt einen Bezeichner zurück, den Sie an den GetBulkDownloadStatus-Vorgang übergeben. Sie rufen den GetBulkDownloadStatus-Vorgang in einer Schleife auf, bis der Download abgeschlossen ist oder fehlschlägt. Die Dauer, für die der Download benötigt wird, hängt von einer Reihe von Variablen ab, z. B. der Anzahl der angeforderten Kampagnen und der Anzahl der Anforderungen, die sich bereits in der Warteschlange befinden. Aufgrund dieser Variablen kann das verwendete Abrufintervall variieren. Sie haben zwei Tage Zeit, um die Datei herunterzuladen, nachdem Sie die Downloadanforderung übermittelt haben. Wenn Sie die Datei innerhalb dieses Zeitraums nicht erfolgreich heruntergeladen haben, wird sie von der Downloadwebsite entfernt, und Sie müssen einen der Downloadvorgänge erneut aufrufen.

  7. Wenn der GetBulkDownloadStatus-Vorgang erfolgreich abgeschlossen wurde, wird die URL der Downloaddatei zurückgegeben. Verwenden Sie die URL, um die Downloaddatei lokal zu kopieren. Die URL muss innerhalb von fünf Minuten nach dem Zeitpunkt verwendet werden, zu dem der GetBulkDownloadStatus-Vorgang einen Success status-Code zurückgibt. Wenn Sie den Download nicht innerhalb dieses Zeitraums starten, müssen Sie GetBulkDownloadStatus erneut aufrufen, um eine neue URL zu erhalten.

  8. Die Downloaddatei ist im ZIP-Format komprimiert, sodass Sie die Datei entzippen müssen, um auf die Daten zuzugreifen. Informationen zum Schema, das für die Downloaddatei verwendet wird, finden Sie unter Massendateischema.

Bewährte Methoden herunterladen

Halten Sie sich an die bewährten Methoden, um eine faire Nutzung für sich selbst und alle Microsoft Advertising-Kunden sicherzustellen.

Wichtig

Während sich genaue Gleichzeitige Download- und Uploadgrenzwerte ändern können, ist die Anzahl der von Ihnen übermittelten ausstehenden Anforderungen begrenzt. Wenn Sie den Fehler 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod beobachten, können Sie Ihre Anforderung erneut übermitteln, nachdem Sie bis zu 15 Minuten gewartet haben, je nach Häufigkeit und Größe der gesendeten Anforderungen. Weitere Informationen finden Sie unter Massen-API-Drosselung.

  • Fordern Sie nur die Massendownloadentitäten an, die Sie benötigen. Neue Datensatztypen (Zeilen) und Felder (Spalten) können jederzeit hinzugefügt werden, und Sie sollten sich nicht auf die Datensatz- oder Feldreihenfolge in der Massendownload- oder Massenupload-Ergebnisdatei verlassen.

  • Führen Sie einen vollständigen Download nur einmal durch. Führen Sie anschließend Deltadownloads aus. Legen Sie LastSyncTimeInUTC auf den Zeitstempel des letzten Downloads fest. Die Downloaddatei enthält den Zeitstempel des Downloads in der SyncTime-Spalte des Kontodatensatzes . Es gibt keinen Vorteil, jedes Mal einen vollständigen Download durchzuführen, und es verringert die Leistung aller, einschließlich Ihrer.

  • Fragen Sie in angemessenen Abständen nach Downloads ab. Sie kennen Ihre Daten besser als jeder andere. Wenn Sie ein Konto herunterladen, das deutlich weniger als eine Million Schlüsselwörter enthält, sollten Sie in Intervallen von 15 bis 20 Sekunden abfragen. Wenn das Konto etwa eine Million Schlüsselwörter enthält, sollten Sie nach fünf Minuten Wartezeit einen Abruf in Intervallen von einer Minute in Erwägung ziehen. Für Konten mit etwa vier Millionen Schlüsselwörtern sollten Sie nach 10 Minuten Wartezeit einen Abruf in Intervallen von einer Minute in Erwägung ziehen.

  • Rufen Sie den DownloadCampaignsByCampaignIds-Vorgang auf, wenn das Konto mehr als vier Millionen Schlüsselwörter enthält. Beim Aufrufen des DownloadCampaignsByAccountIds-Vorgangs mit einem Konto, das mehr als vier Millionen Schlüsselwörter enthält, tritt ein Fehler auf.

  • Möglicherweise möchten Sie weniger Kampagnen in Ihre DownloadCampaignsByCampaignIds-Anforderung aufnehmen. Das Aufrufen des DownloadCampaignsByCampaignIds-Vorgangs mit einem Konto, das mehr als acht Millionen Schlüsselwörter enthält, schlägt fehl. Anforderungen, die weniger Kampagnen pro Anruf angeben, werden in der Regel früher abgeschlossen als Anrufe, die die maximal zulässige Anzahl angeben.

Massenupload

Sie können Ihre Massenuploaddatei mit HTTP POST an eine url übermitteln, die vom Massendienst bereitgestellt wird.

Hinweis

Die Dateigrößenbeschränkung für den Upload in der Produktion beträgt 100 MB und bis zu 4 Millionen Zeilen. Für Sandbox beträgt der Grenzwert 20.000 Zeilen.

Informationen zum Schema, das Sie für die Uploaddatei verwenden sollten, finden Sie unter Massendateischema.

Hochladen einer Massendatei

Es folgt eine Übersicht über die Anforderungseinstellungen und den Uploadworkflow.

Wichtig

Sie müssen im gesamten GetBulkUploadUrl-, HTTP POST- und GetBulkUploadStatus-Workflow dieselben Benutzeranmeldeinformationen verwenden.

  1. Legen Sie das AccountId-Element der GetBulkUploadUrl-Anforderung auf den Kontobezeichner fest, der den daten entspricht, die hochgeladen werden.

  2. Legen Sie das ResponseMode-Element der GetBulkUploadUrl-Anforderung fest, um anzugeben, ob der Dienst Fehler und die entsprechenden Daten oder nur die Fehler in der Ergebnisdatei zurückgeben soll. Weitere Informationen finden Sie unter ResponseMode.

  3. Verwenden Sie die UploadUrl , die mit der GetBulkUploadUrl-Antwort zurückgegeben wird, um Ihre Massenuploaddatei mit HTTP POST zu übermitteln. Der Inhaltstyp muss multipart/form-data sein. UTF-8-Dateien müssen die Bytereihenfolgemarkierung (BOM) enthalten. Der ZIP-komprimierte Upload sollte eine Datei enthalten, die entweder als CSV oder Tsv formatiert ist. Die ZIP-Datei muss ordnungsgemäß strukturiert sein, einschließlich eines Endes des zentralen Verzeichnisdatensatzes.

    Hinweis

    Der HTTP-Standardautorisierungsheader wird nicht verwendet. Zur Authentifizierung müssen Sie die benutzerdefinierten Microsoft Advertising-Headerelemente Ihres HTTP-Clients hinzufügen und festlegen, einschließlich der Header DeveloperToken, CustomerId und CustomerAccountId . Sie müssen die Benutzeranmeldeinformationen auch über das AuthenticationToken-Headerelement festlegen. Weitere Informationen finden Sie unter Authentifizierung mit OAuth und Verwendung der API-Anmeldeinformationen.

    Sie müssen im gesamten GetBulkUploadUrl-, HTTP POST- und GetBulkUploadStatus-Workflow dieselben Benutzeranmeldeinformationen verwenden.

    Hier ein Beispiel:

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

  4. Überprüfen Sie die HTTP-Antwort status Code. Wenn die HTTP-Antwort status Code 200 ist, wurde die Datei erfolgreich von Microsoft Advertising empfangen. Wenn die HTTP-Antwort status Code 401 ist, ist die Authentifizierung fehlgeschlagen, z. B. AuthenticationToken oder DeveloperToken war ungültig. Wenn die HTTP-Antwort status Code 400 ist, sollten Sie auch den Antwortdatenstrom für Bing Ads-API-Vorgangsfehlercodes überprüfen, z. B. im Bereich von 3220 bis 3227.

    Hier sehen Sie eine Beispielfehlerantwortmeldung, dass die URL bereits zum Hochladen einer Massendatei verwendet wurde.

    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. Die GetBulkUploadUrl-Antwort enthält auch eine RequestId , die Sie an den GetBulkUploadStatus-Vorgang übergeben. Während der Upload aussteht, können Sie den GetBulkUploadStatus-Vorgang in einer Schleife aufrufen, bis der Upload abgeschlossen ist oder fehlschlägt. Sie haben fünfzehn Minuten Zeit, um die Uploadergebnisdatei herunterzuladen, nachdem Sie die Uploadanforderung übermittelt haben. Wenn Sie die Datei innerhalb dieses Zeitraums nicht erfolgreich heruntergeladen haben, wird sie von der Downloadwebsite entfernt und möglicherweise nicht abgerufen. Wenn Sie dieses Zeitfenster verpassen, können Sie einen der Downloadvorgänge aufrufen, um die neuesten Entitätsdaten abzurufen.

  6. Wenn der GetBulkUploadStatus-Vorgang erfolgreich abgeschlossen wird, wird die URL der Uploadergebnisdatei zurückgegeben. Verwenden Sie die URL, um die Ergebnisdatei lokal zu kopieren. Die URL muss innerhalb von fünfzehn Minuten nach dem Zeitpunkt verwendet werden, zu dem der GetBulkUploadStatus-Vorgang die Antwortzeichenfolge Abgeschlossen status zurückgibt. Wenn Sie den Download nicht innerhalb dieses Zeitraums starten, müssen Sie GetBulkUploadStatus erneut aufrufen, um eine neue URL zu erhalten.

    Hinweis

    Das Format der Uploadergebnisdatei ist entweder CSV oder Tsv und entspricht dem Format der Datei, die Sie zum Hochladen übermittelt haben.

Bewährte Methoden zum Hochladen

Halten Sie sich an die bewährten Methoden, um eine faire Nutzung für sich selbst und alle Microsoft Advertising-Kunden sicherzustellen.

Wichtig

Während sich genaue Gleichzeitige Download- und Uploadgrenzwerte ändern können, ist die Anzahl der von Ihnen übermittelten ausstehenden Anforderungen begrenzt. Wenn Sie den Fehler 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod beobachten, können Sie Ihre Anforderung erneut übermitteln, nachdem Sie bis zu 15 Minuten gewartet haben, je nach Häufigkeit und Größe der gesendeten Anforderungen. Weitere Informationen finden Sie unter Massen-API-Drosselung.

  • Große Dateien können die Uploadleistung beeinträchtigen. Es ist optional und empfiehlt, die Datei für den Upload zu komprimieren. Falls komprimiert, muss es als ZIP mit der entsprechenden Erweiterung formatiert werden. Die Dateigrößenbeschränkung für den Upload in der Produktion beträgt 100 MB und bis zu 4 Millionen Zeilen. Für Sandbox beträgt der Grenzwert 20.000 Zeilen. Wenn Sie gleichzeitige Uploads pro Kunde unter 5 oder 6 beschränken können, sollten Sie erwägen, die Datei aufzuteilen, anstatt sich der Dateigrößenbeschränkung zu nähern.

  • Beschränken Sie gleichzeitige Uploads auf 5 oder 6 pro Kunde, um Dateien parallel hochzuladen. Warten Sie bei jedem Thread, bis die vorherige Datei verarbeitet wurde. Anschließend können Sie den Thread wiederverwenden, um eine andere Datei hochzuladen. Beispielsweise kann ein Thread eine Datei hochladen, und nach dem Hochladen status entweder Completed, CompletedWithErrors oder Failed ist, kann dieser Thread eine andere Datei hochladen.

  • Laden Sie nur die Entitäten und Felder hoch, die Sie hinzufügen oder aktualisieren. Wenn angegeben, werden schreibgeschützte Felder wie Gebotsvorschläge und Qualitätsbewertungsdaten ignoriert.

  • Laden Sie einen Entitätstyp pro Datei hoch, um die Leistung zu maximieren. Es gibt einige Ausnahmen, z. B. wenn neue Kampagnen, Anzeigen und Schlüsselwörter erstellt werden, kann es effizienter sein, diese zusammen mit Referenzschlüsseln hochzuladen. Ein weiteres Beispiel: Wenn Sie nur 10 Kampagnen, 500 Anzeigen und 800 Schlüsselwörter aktualisieren, können Sie diese in einen Upload einschließen, anstatt Uploads nach Typ aufzuteilen.

  • Überlegen Sie, ob Sie Fehler und Ergebnisse (ResponseMode = ErrorsAndResults) in der Uploadergebnisdatei anfordern müssen, oder ob nur Fehler (ResponseMode = ErrorsOnly) ausreichen. Überlegen Sie, ob Sie die Ergebnisse mit Ihren lokalen Daten synchronisieren sollten. Wenn Sie z. B. Entitäten aktualisieren, müssen Sie möglicherweise nur wissen, ob Fehler aufgetreten sind. In diesem Fall können Sie ResponseMode = ErrorsOnly in der GetBulkUploadUrl-Anforderung angeben. Wenn Sie neue Entitäten hinzufügen, können Sie ResponseMode = ErrorsAndResults in der GetBulkUploadUrl-Anforderung angeben, um die resultierenden Entitätsbezeichner zu empfangen.

  • Laden Sie bei teilweisen Wiederholungsversuchen nicht die gesamte Datei hoch, wenn nur eine Teilmenge der Datensätze zu Fehlern geführt hat. Laden Sie nur die Datensätze hoch, die Sie wiederholen möchten.

  • Wiederholen Sie den Vorgang erst, wenn der Upload status entweder Completed, CompletedWithErrors oder Failed lautet. Wenn die Leistung zufällig nicht den Erwartungen entspricht, warten Sie trotzdem auf das Ergebnis.

  • Fragen Sie in angemessenen Abständen nach Uploadergebnissen ab. Zunächst sollten Sie eine Minute für alle hochgeladenen 10.000 Zeilen warten. Nach der anfänglichen Wartezeit sollten Sie einen Abruf in Intervallen von einer Minute in Betracht ziehen.

Siehe auch

Massendienstreferenz
Adressen des Bing Ads-API-Webdiensts