Verwalten Ihrer Produkte

  • Artikel

Die Inhalts-API ist eine RESTful-API, die die Ressource Products verwendet, um Produktangebote in Ihrem Microsoft Merchant Center-Store (MMC) zu verwalten.

Im Folgenden sehen Sie den Basis-URI, den Sie zum Aufrufen der Inhalts-API verwenden.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

Jede HTTP-Anforderung muss das OAuth-Zugriffstoken des Benutzers und Ihr Entwicklertoken enthalten. Um das Zugriffstoken des Benutzers anzugeben, legen Sie den AuthenticationToken-Header fest. Um Ihr Entwicklertoken anzugeben, legen Sie den DeveloperToken-Header fest.

Wenn Sie Kataloge im Namen anderer Kunden verwalten, müssen Sie Folgendes festlegen:

  • Der CustomerId-Header zur Kunden-ID des Kunden, dessen Geschäft Sie verwalten.
  • Der CustomerAccountId-Header auf die Konto-ID eines der Konten des Kunden, die Sie verwalten (es spielt keine Rolle, welches verwaltete Konto verwendet wird).

Standardmäßig verwendet die Inhalts-API JSON-Objekte, um das Produktangebot darzustellen. Um XML zu verwenden, legen Sie den Abfrageparameter alt auf XML fest.

Ausführliche Informationen zur Verwendung der Products-Ressource finden Sie in den folgenden Abschnitten.

Abrufen eines Produktangebots aus dem Store

Um ein bestimmtes Produktangebot aus dem Store zu erhalten, fügen Sie die folgende Vorlage an den Basis-URI an.

{mmcMerchantId}/products/{productUniqueId}

Legen Sie {mmcMerchantId} auf Ihre MMC-Store-ID und auf die vollqualifizierte Produkt-ID (z. B. Online:en:US:Sku123) und nicht auf die offerId des Produkts fest{productUniqueId}. Da bei der Produkt-ID die Groß-/Kleinschreibung beachtet wird, verwenden Sie die ID, die die API beim Hinzufügen des Produkts an Sie zurückgegeben hat.

Senden Sie eine HTTP GET-Anforderung an die resultierende URL. Wenn das Produkt gefunden wurde, enthält die Antwort ein Product-Objekt , das das Angebot enthält.

Wenn Sie ein Produkt mit derselben ID in mehrere Kataloge eingefügt haben, gibt der Dienst nur einen davon zurück– welches Produkt und welcher Katalog nicht bestimmt ist. Aus diesem Gründen sollten Sie ein Produkt mit derselben Produkt-ID nicht in mehrere Kataloge einfügen.

Ein Codebeispiel, das zeigt, wie Ein Produktangebot abgerufen wird, finden Sie unter Codebeispiel für die Verwaltung von Produkten.

Abrufen einer Liste von Produktangeboten aus dem Store

Um eine Liste der Produktangebote abzurufen, die sich im Store befinden, fügen Sie die folgende Vorlage an den Basis-URI an.

{mmcMerchantId}/products

Legen Sie auf Ihre MMC-Speicher-ID fest {mmcMerchantId} .

Verwenden Sie zum Durchblättern der Liste der Angebote die Abfrageparameter max-results und start-token . Legen Sie in Ihrem ersten Aufruf auf die maximale Anzahl von Angeboten fest max-results , die der Dienst zurückgeben soll. Die maximale Anzahl von Angeboten, die der Dienst zurückgeben kann, ist 250. Der Standardwert ist 25. Senden Sie eine HTTP GET-Anforderung an die resultierende URL. Im Folgenden sehen Sie ein Beispiel für die Anforderung.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

Wenn der Store Angebote enthält, enthält die Antwort ein Product-Objekt , das bis zur angeforderten Anzahl von Angeboten enthält.

Wenn weitere Angebote verfügbar sind, enthält die Antwort das nextPageToken Feld (siehe Produkte). Das nextPageToken Feld enthält den Tokenwert, den Sie verwenden, um den start-token Parameter in Ihrer nächsten List-Anforderung auf festzulegen. Im Folgenden sehen Sie ein Beispiel, in dem das Token verwendet wird.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

Ein Codebeispiel, das zeigt, wie Sie eine Liste von Produktangeboten abrufen, finden Sie unter Codebeispiel für Die Verwaltung von Produkten.

Löschen eines Angebots aus dem Store

Um ein bestimmtes Produktangebot aus dem Store zu löschen, fügen Sie die folgende Vorlage an den Basis-URI an.

{mmcMerchantId}/products/{productUniqueId}

Legen Sie {mmcMerchantId} auf Ihre MMC-Store-ID und auf die vollqualifizierte Produkt-ID (z. B. Online:en:US:Sku123) und nicht auf die offerId des Produkts fest{productUniqueId}. Da bei der Produkt-ID die Groß-/Kleinschreibung beachtet wird, verwenden Sie die ID, die die API beim Hinzufügen des Produkts an Sie zurückgegeben hat.

Senden Sie eine HTTP DELETE-Anforderung an die resultierende URL. Wenn das Produkt gefunden wurde, wird es gelöscht.

Wenn Sie ein Produkt mit derselben Produkt-ID in mehrere Kataloge eingefügt haben, löscht der Dienst alle. Sie sollten ein Produkt mit derselben Produkt-ID nicht in mehrere Kataloge einfügen.

Ein Codebeispiel, das zeigt, wie ein Produktangebot gelöscht wird, finden Sie unter Codebeispiel für die Verwaltung von Produkten.

Hinzufügen und Aktualisieren eines Produktangebots

Das Hinzufügen oder Aktualisieren eines Angebots ist ein Einfügevorgang. Da eine Aktualisierung ein Einfügevorgang ist, müssen Sie alle Felder des Angebots in die Anforderung einschließen. Sie können kein einzelnes Feld aktualisieren.

Fügen Sie zum Einfügen eines Produktangebots die folgende Vorlage an den Basis-URI an.

{mmcMerchantId}/products

Legen Sie auf Ihre MMC-Speicher-ID fest {mmcMerchantId} .

Beim Senden einer HTTP POST-Anforderung an die resultierende URL wird das Angebot in den Standardspeicherkatalog geschrieben. Um das Angebot in einen bestimmten Katalog zu schreiben, schließen Sie den Abfrageparameter bmc-catalog-id ein.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

Wenn das Produkt eingefügt wurde, enthält die Antwort ein Product-Objekt . Das Product -Objekt enthält die Produkt-ID, die Sie zum Abrufen und Löschen des Angebots verwenden.

Ein Angebot muss die folgenden Felder enthalten:

Die API verwendet , channelcontentLanguage, targetCountryund offerId , um die Produkt-ID zu generieren. Da diese Felder zum Generieren der ID verwendet werden, dürfen Sie sie nicht aktualisieren. Bei der Produkt-ID wird die Groß-/Kleinschreibung beachtet. die ID verwendet die gleiche Groß-/Kleinschreibung, die Sie zum Angeben channelvon , contentLanguage, targetCountryund offerIdverwendet haben.

Achtung

Achten Sie darauf, die gleiche Groß-/Kleinschreibung für channel, contentLanguage, targetCountryund offerId zu verwenden, da Sie dasselbe Produkt effektiv mehrmals hinzufügen können, wenn sich die Groß-/Kleinschreibung unterscheidet.

Die folgenden Felder sind auch erforderlich, wenn der Hersteller Werte zugewiesen hat.

Sie müssen die Werte angeben, sofern bekannt. Wenn Sie keine davon angeben, müssen Sie das Feld identifierExists auf false festlegen. The default is true.

Wenn bekannt ist, dass das Produkt über diese Bezeichner verfügt und Sie sie nicht angeben, akzeptiert MMC das Produkt vorerst, aber das Product -Objekt in der Antwort enthält das warnings Feld. Sie sollten immer überprüfen, ob das warnings Feld vorhanden ist, und alle identifizierten Probleme beheben.

Zusätzlich zu den erforderlichen Feldern sollten Sie auch das Datum und die Uhrzeit angeben, an dem das Angebot abläuft (siehe expirationDate). Standardmäßig läuft das Angebot 30 Tage ab dem Datum und der Uhrzeit ab, an dem es in den Store oder Katalog geschrieben wird. Sie sollten Produkte nachverfolgen, die sich dem Ablauf nähern und vor dem Ablauf entweder ihr Ablaufdatum aktualisieren oder einfach das Produkt aktualisieren (Sie müssen keines der Felder des Produkts aktualisieren), wodurch das Ablaufdatum automatisch um weitere 30 Tage verlängert wird. Wenn Sie das Ablaufdatum explizit festlegen, müssen Sie selbst ein neues Ablaufdatum festlegen. Wenn Sie das Produkt aktualisieren, wird das Ablaufdatum in diesem Fall nicht automatisch um weitere 30 Tage verlängert.

Alle anderen Felder gelten als optional; Sie sollten jedoch so viele angeben, wie erforderlich sind, um das Produkt genau zu beschreiben.

Hinweis

Das Product -Objekt darf nur Felder enthalten, die auf Werte festgelegt sind. Schließen Sie keine NULL-Felder in das -Objekt ein Product . Schließen Sie z. B. nicht ein "adult":null.

Microsoft verwendet nicht alle Product Felder. Eine Liste der Felder, die die API akzeptiert, aber nicht verwendet, finden Sie unter Welche Google-Attribute kann ich verwenden? Alle anderen von Microsoft verwendeten Felder werden verwendet, um die Produkte bei der Bereitstellung von Produktanzeigen zu filtern.

Wenn Sie ein Feld angeben, das der Inhalts-API unbekannt ist, ignoriert der Dienst das Feld.

Wenn Sie ein Angebot einfügen, führt der Dienst grundlegende Überprüfungen für das Angebot durch und gibt ggf. Fehler und Warnungen zurück. Wenn ein Fehler auftritt, enthält die Antwort ein ErrorResponse -Objekt. Wenn Warnungen auftreten, enthält die Antwort ein Product -Objekt, und das warnings Feld listet die Warnungen auf.

Wenn das Angebot die grundlegenden Validierungen besteht, wird es Offlineüberprüfungen und -überprüfungen, z. B. redaktionelle Rezensionen, unterzogen, die bis zu 36 Stunden dauern können. Das Angebot wird erst ausgeführt, wenn alle Überprüfungen und Überprüfungen abgeschlossen sind. Verwenden Sie die Ressource Status, um die status eines Angebots zu ermitteln.

Beachten Sie, dass die API keine Parallelitätssteuerelemente wie ETags bereitstellt. Wenn zwei Apps versuchen, dasselbe Produkt hinzuzufügen oder zu aktualisieren, gewinnt die letzte.

Ein Angebot, das in einer Produktanzeige angezeigt wird, umfasst den Preis, den Titel, den Geschäftsnamen (oder sellerName, falls angegeben), den Link zur Webseite, die weitere Informationen zum Produkt enthält, und ein Bild des Produkts.

Erstellen Sie für Bekleidungsprodukte, die in mehreren Farben, Mustern oder Materialien verfügbar sind, ein Produkt für jede Variante, und verwenden Sie das Feld itemGroupId , um alle Produktvarianten zu gruppieren.

Ein Codebeispiel zum Einfügen eines Produktangebots finden Sie unter Codebeispiel für Die Verwaltung von Produkten.

Verwenden der Batchverarbeitung

Wenn Sie mehrere Produktangebote verarbeiten, sollten Sie die Verwendung der Batchverarbeitungsfunktion der API in Betracht ziehen. Mit diesem Feature können Sie mehrere Einfüge-, Abruf- und Löschvorgänge in einer einzelnen Anforderung verarbeiten. Die Verarbeitung mehrerer Angebote in derselben Anforderung ist effizienter als das Senden einer separaten Anforderung für jedes Angebot. Die Kosten, die bei der Verarbeitung einer einzelnen Anforderung anfallen, verteilen sich auf die Tausenden von Angeboten in der Batchanforderung, anstatt diese Kosten für jede einzelne Anforderung anfällt.

Fügen Sie dasselbe Produkt nicht in derselben Anforderung ein, rufen sie nicht ein oder löschen Sie es ab.

Um eine Batchanforderung zu senden, fügen Sie die folgende Vorlage an den Basis-URI an.

{mmcMerchantId}/products/batch

Legen Sie auf Ihre MMC-Speicher-ID fest {mmcMerchantId} .

Beim Senden einer HTTP POST-Anforderung an die resultierende URL werden die Einfügevorgänge auf den Standardspeicherkatalog angewendet. Um die Angebote auf einen bestimmten Katalog anzuwenden, schließen Sie den Abfrageparameter bmc-catalog-id ein.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

Der Text des POST ist ein Batch-Objekt , das ein Array von Item-Objekten enthält. Legen Sie für alle Vorgänge die batchIdFelder , merchantId und method fest. ist batchId eine benutzerdefinierte ID, die Sie verwenden, um das Batchelement in der Antwort zu identifizieren. die merchantId ist Ihre Speicher-ID, und die method ist der auszuführende Vorgang (z. B. Einfügen, Löschen oder Abrufen).

Wenn method eingefügt ist, legen Sie das product Feld auf ein Product-Objekt fest, das das hinzuzufügende oder zu aktualisierende Angebot enthält. method Wenn ein Abrufen oder Löschen ist, legen Sie andernfalls auf die vollqualifizierte ID des Angebots festproductId, das Sie abrufen oder löschen möchten.

Die Größe des Texts einer Batchanforderung darf 4 MB nicht überschreiten. Wenn der Text 4 MB überschreitet, gibt die Antwort HTTP-status Code 413 zurück. Abhängig von der Größe der einzelnen Angebote (anzahl der von Ihnen angegebenen Felder) können Sie zwischen 2.000 und 6.000 Angebote senden. Wenn Sie den Text komprimieren, können Sie die maximale Anzahl von Angeboten senden, die je nach Größe 12.000 beträgt.

Um den Text zu komprimieren, verwenden Sie nur die GZip-Komprimierung, und legen Sie den Content-Encoding-Header der Anforderung auf gzip fest.

Der Dienst verarbeitet jedes Element im Batch. Die Antwort enthält ein Batch -Objekt, das jedes Item in der Anforderung enthaltene Objekt enthält. Beachten Sie, dass es keine Garantie dafür gibt, dass die Reihenfolge der Elemente in der Antwort in der gleichen Reihenfolge wie die Elemente in der Anforderung liegt.

Bei Einfügevorgängen enthält das Element nur die batchId Felder und product . Das product Feld enthält das gleiche Angebot, das Sie in der Anforderung gesendet haben, enthält aber auch die vollqualifizierte Produkt-ID. Wenn ein Fehler oder eine Warnung auftritt, enthält das Element die batchIdFelder , methodund error . Das error Feld enthält die Gründe, warum die Einfügung fehlgeschlagen ist, oder Warnungen zu Problemen mit dem Angebot, die Sie beheben müssen.

Für Get-Vorgänge enthält das Element die batchId Felder und product . Das product Feld enthält das von Ihnen angeforderte Angebot. Wenn das Produkt nicht gefunden wird, enthält das -Objekt das product -Feld nicht.

Bei Löschvorgängen enthält das Element nur das batchId Feld. Es gibt keinen Hinweis darauf, ob das Angebot vorhanden ist und gelöscht wurde.

Ein Codebeispiel zur Verwendung der Batchverarbeitung finden Sie unter Erstellen einer Batchanforderung.