Bing Ads-API-Dienstprotokoll

Sie können Ihre Bing Ads-API-Anwendung in jeder Sprache schreiben, die Webdienste unterstützt. Für jeden Webdienst wird ein WSDL-Dokument (Web Services Description Language) definiert. Die WSDL definiert die Vorgänge, die ein Webdienst bietet, sowie das Format der Anforderungs- und Antwortnachrichten, die der Client an die Vorgänge sendet und von diesen empfängt. Die Anforderungs- und Antwortnachrichten definieren die Namen und Typen der Daten, die der Client mit dem Vorgang austauscht. Weitere Informationen zu WSDLs finden Sie in der W3C-WSDL-Spezifikation.

SOAP für Bing Ads-API

Die Bing Ads-API unterstützt SOAP (Simple Object Access Protocol). Einige Sprachen, z. B. C# und Java, stellen Tools bereit, die Proxyklassen aus der WSDL generieren. Wenn Die Sprache Ihrer Wahl kein Tool zum Generieren von Proxyklassen bereitstellt, müssen Sie Ihre eigenen Proxyklassen oder SOAP-Umschläge generieren. Zum Generieren der Proxyklassen benötigen Sie die Webadresse des WSDL-Dokuments des Diensts, den Sie verwenden möchten. Die Microsoft Advertising-Sandbox- und Produktionsumgebungen verfügen jeweils über eine eindeutige Adresse. Die Adressen enthalten auch die Versionsnummer der WSDL, die für ein Hauptrelease der Bing Ads-API spezifisch ist. Informationen zu Produktions- und Sandboxdienst-WSDLs der neuesten Version der Bing Ads-API finden Sie unter Webdienstadressen der Bing Ads-API.

SOAP-XML-Elementreihenfolge

Wenn Sie eine SOAP-Anforderungsnachricht erstellen, ist die Reihenfolge der Elemente im SOAP-Text von entscheidender Bedeutung. Die Elemente müssen in derselben Reihenfolge wie in der Webdienstbeschreibungssprache (WSDL) definiert sein. Wenn die erforderlichen Elemente nicht in der richtigen Reihenfolge sind, schlägt der Aufruf fehl. Wenn die optionalen Elemente nicht in der richtigen Reihenfolge sind, kann der Aufruf fehlschlagen, oder die Elemente werden ignoriert. Die WSDL-Syntax, die die richtige Reihenfolge der Elemente anzeigt, ist in jeder Anforderungsnachricht, Antwortnachricht und jedem Datenobjekt enthalten, die im Referenzinhalt dokumentiert sind. Darüber hinaus zeigt jede Anforderungs- und Antwortnachricht einen SOAP-Beispielumschlag an.

Hinweis

Bei XML wird die Groß-/Kleinschreibung beachtet. Sie müssen die richtige Groß-/Kleinschreibung für die Wertnamen verwenden. Stark typisierte Programmiersprachen wie C# stellen sicher, dass Sie die richtige Groß-/Kleinschreibung haben, bevor Sie kompilieren können. Andere Sprachen führen möglicherweise nicht zu einem Kompilierungsfehler, wenn nicht die richtige Groß-/Kleinschreibung verwendet wird. Der Code schlägt jedoch zur Laufzeit fehl.

Teilerfolg

Die Bing Ads-API unterstützt teilweise Vervollständigungen für Add-, Update- und Löschvorgänge. Wenn eines der Objekte in der Liste der Objekte, die Sie hinzufügen, aktualisieren oder löschen, fehlschlägt, kann der Vorgang für andere Objekte in der Auflistung erfolgreich sein. Wenn Sie einen Get-Vorgang aufrufen, der eine Liste von Bezeichnern akzeptiert, z. B. den Vorgang GetKeywordsByIds , und einer der Bezeichner in der Liste ist ungültig, ist der Vorgang erfolgreich, und das Antwortelement, das dem ungültigen Anforderungsbezeichner entspricht, ist null.

Teilaktualisierung

Teilweise Aktualisierung der Kampagnenverwaltung

Partielle Aktualisierungen werden für die meisten, aber nicht für alle Datenobjekte der Kampagnenverwaltung unterstützt. Wenn Sie beispielsweise die Text-Eigenschaft eines ExpandedTextAd-Objekts aktualisieren, müssen Sie nur die Elemente Id und Text angeben. Schreibgeschützte Elemente wie die status müssen null oder leer bleiben. Sofern nicht anders dokumentiert, bleiben die optionalen Elemente möglicherweise leer, und ihre vorhandenen Einstellungen bleiben unverändert.

Teilaktualisierungen werden für Anzeigenerweiterungen nicht unterstützt. Alle optionalen Elemente, die nicht mit der Updateanforderung gesendet werden, werden tatsächlich aus der jeweiligen Anzeigenerweiterung gelöscht.

Teilaktualisierung der Kundenverwaltung

Der Kundenverwaltungsdienst führt eine vollständige Aktualisierung der Entitäten durch, sodass Sie zusätzlich zu den dokumentierten erforderlichen Eigenschaften Werte für alle optionalen Eigenschaften angeben müssen, die nicht null oder leer sein sollen.

Hinweis

Eine Ausnahme von dieser Regel ist das ForwardCompatibilityMap-Element eines beliebigen Objekts. Wenn Sie z. B. das ForwardCompatibilityMap-Element des AdvertiserAccounts nicht angeben, aktualisiert oder nullisiert der Dienst keine Eigenschaften, die andernfalls durch Schlüssel-Wert-Paare dargestellt worden wären.

Lokales Speichern Ihrer Entitätsbezeichner

Sie sollten einen lokalen Speicher für Ihre Konto- und Kampagnenentitäten verwalten. Insbesondere sollten Sie die Bezeichner Ihrer Konten, Kunden, Kampagnen, Anzeigengruppen und Schlüsselwörter lokal speichern. Die meisten Aufrufe erfordern den Bezeichner der Entität. Wenn Sie den Bezeichner speichern, entfernen Sie den Aufruf, der zum Abrufen des Bezeichners erforderlich ist.

Viele der Kampagnenverwaltungsaufrufe erfordern beispielsweise einen Kontobezeichner. Um den Kontobezeichner abzurufen, können Sie den Kundenverwaltungsdienst verwenden. Anstatt den Dienst jedoch wiederholt aufzurufen, speichern Sie den Kontobezeichner lokal, damit Sie ihn in nachfolgenden Aufrufen verwenden können.

Verwalten des Mit dem Ausführen von Webdienstaufrufen verbundenen Mehraufwands

Im Folgenden sind die Mehraufwand für die Verarbeitungszeit aufgeführt, die mit jedem Webdienstaufruf verbunden sind.

• Herstellen einer HTTPS-Verbindung mit dem Webdienst.
• Authentifizieren des Benutzernamens und des Kennworts.
• Überprüfen des Entwicklertokens.

Diese Kosten fallen unabhängig davon an, ob Sie einen einzelnen Artikel oder eine Gruppe von Elementen verarbeiten. Um den Mehraufwand zu minimieren, sollten Sie im Allgemeinen versuchen, so viele Elemente wie möglich in einem Aufruf zu verarbeiten. Anstatt z. B. UpdateCampaigns für jede Kampagne aufzurufen, die Sie aktualisieren möchten, rufen Sie es nur einmal für mehrere Kampagnen auf, die Sie aktualisieren möchten. Um umfangreiche Daten zu verwalten, insbesondere wenn Sie Anzeigen und Schlüsselwörter in mehreren Anzeigengruppen oder Kampagnen in einem Konto hinzufügen oder aktualisieren müssen, sollten Sie den Massendienst verwenden. Mit dem Massendienst können Sie Daten als TSV- oder CSV-Datei herunterladen, sie nach Bedarf ändern und dann Ihre Änderungen hochladen. Weitere Informationen zur Verwendung des Massendiensts finden Sie unter Massendownload und -upload.

Aufgrund der Kosten, die mit dem Herstellen einer Verbindung mit einem Webdienst verbunden sind, sollten Sie die Verbindung so lange beibehalten, wie sie benötigt wird. Wenn Sie z. B. mehrere Berichte anfordern müssen, verwenden Sie dasselbe Reporting Service-Clientobjekt für alle Aufrufe des Berichterstellungsdienstvorgangs. Schließen Sie die Verbindung explizit, wenn Sie den Dienst nicht mehr benötigen.

Behandeln der Drosselung

Die Drosselung der Nutzung mit extrem hohem Volumen sorgt für eine faire Nutzung für alle Microsoft Advertising-Clients.

Ad Insight-API

Für den Ad Insight-Dienst schränkt die Drosselung die Anzahl der Aufrufe an die API ein, die jeder Benutzer in einer Minute durchführen kann.

Auf Kundenebene wird die Anzahl der Anrufe, die ein Kunde an die Kundendaten tätigen kann, mithilfe eines gleitenden Protokolls mit einem 60-Sekunden-Fenster eingeschränkt.

Wenn Sie den Grenzwert für Dienstaufrufe überschreiten, wird der folgende Fehler angezeigt:

• Numerischer Fehlercode: 117
• Symbolischer Fehlercode: CallRateExceed
• Nachricht: Sie haben die Anzahl der Anrufe überschritten, die Sie in einer Minute tätigen dürfen. Bitte reduzieren Sie die Anzahl der Anrufe, die Sie pro Minute tätigen.

Wenn Sie diesen Fehler feststellen, können Sie die Anforderung nach 60 Sekunden erneut unter dem Grenzwert übermitteln.

Massen-API

Der Massendienst beschränkt die Anzahl der Anforderungen, die Sie an DownloadCampaignsByAccountIds, DownloadCampaignsByCampaignIds und GetBulkUploadUrl stellen können. Die Details der Dienstgrenzwerte sind intern und können sich ändern.

Wenn Sie den Grenzwert für Dienstaufrufe erreichen, wird der folgende Fehler angezeigt:

• Numerischer Fehlercode: 4204
• Symbolischer Fehlercode: BulkServiceNoMoreCallsPermittedForTheTimePeriod
• Meldung: Für dieses Konto sind für den aktuellen Zeitraum keine Massenupload- oder Downloadanrufe mehr zulässig. Wenn Sie Ihr Massenuploadlimit erreicht haben, sind die Massendownloadvorgänge möglicherweise weiterhin verfügbar oder umgekehrt.

Wenn Sie diesen Fehler feststellen, können Sie Ihre Anforderung nach einer Wartezeit von bis zu 15 Minuten erneut übermitteln. Weitere Informationen finden Sie unter Bewährte Methoden für Massendownloads und Bewährte Methoden für den Massenupload.

Beachten Sie außerdem, dass das Größenlimit pro Datei für den Massenupload in der Produktion 100 MB und bis zu 4 Millionen Zeilen beträgt. Für Sandbox beträgt der Grenzwert 20.000 Zeilen.

Kampagnenverwaltungs-API

Für den Kampagnenverwaltungsdienst schränkt die Drosselung die Anzahl der Aufrufe an die API ein, die jeder Benutzer in einer Minute durchführen kann.

Auf Kundenebene wird die Anzahl der Anrufe, die ein Kunde an die Kundendaten tätigen kann, mithilfe eines gleitenden Protokolls mit einem 60-Sekunden-Fenster eingeschränkt.

Wenn Sie den Grenzwert für Dienstaufrufe erreichen, wird der folgende Fehler angezeigt:

• Numerischer Fehlercode: 117
• Symbolischer Fehlercode: CallRateExceed
• Nachricht: Sie haben die Anzahl der Anrufe überschritten, die Sie in einer Minute tätigen dürfen. Bitte reduzieren Sie die Anzahl der Anrufe, die Sie pro Minute tätigen.

Wenn Sie diesen Fehler feststellen, können Sie die Anforderung nach 60 Sekunden erneut unter dem Grenzwert übermitteln.

Berichterstellungs-API

Der Reporting Service beschränkt die Anzahl der Anforderungen, die Sie an SubmitGenerateReportRequest senden können. Die Details der Dienstgrenzwerte sind intern und können sich ändern.

Wenn Sie den Grenzwert für Dienstaufrufe erreichen, wird der folgende Fehler angezeigt:

• Numerischer Fehlercode: 207
• Symbolischer Fehlercode: ConcurrentRequestOverLimit
• Meldung: Sie haben die maximale Anzahl gleichzeitiger Berichtsanforderungen bereits erreicht. Warten Sie, bis die vorherigen Berichte abgeschlossen sind, und versuchen Sie dann, eine neue Anforderung zu übermitteln.

Wenn Sie diesen Fehler feststellen, warten Sie, bis die vorherigen Berichte abgeschlossen sind, und versuchen Sie dann, eine neue Anforderung zu übermitteln.

Siehe auch

Adressen des Bing Ads-API-Webdiensts
Übersicht über die Bing Ads-API