Produktaufrufe

Wir möchten die Betaversion der Merchant API vorstellen. Es handelt sich dabei um die neue Version der Content API und die Zukunft.

Die Ressource products bietet ein hohes Maß an Flexibilität und Kontrolle über mehr als 60 Produktattribute.Einige Felder sind Pflichtfelder, die enthalten sein müssen, um für die Anzeige auf Google Shopping genehmigt zu werden. Es gibt eine Reihe optionaler Felder, die je nach Standort, Produkttyp, Produktvarianten und Produktsets zu Pflichtfeldern werden können. Weitere Informationen zu den über 60 optionalen Parametern, die für Produkte konfiguriert werden können, finden Sie in den Produktdatenspezifikationen.

Mit der Ressource products können Sie ein Produkt nach dem anderen insert, get, update und delete sowie list alle Produkte in der Merchant Center-Datenbank speichern.

Mit der Ressource productstatuses kann der Genehmigungs- oder Ablehnungsstatus eines bestimmten Produkts für ein Ziel geprüft werden. Im Leitfaden zum Produktstatus finden Sie weitere Informationen dazu, bei welchen Produkten es Probleme mit der Datenqualität gibt und was diese Probleme sein können.

In unseren API-Beispielen verwenden wir drei Produkte: zwei Google-T-Shirts und eine Google-Mütze. Wir verwenden einen minimalen Satz von Produktdaten, der in der folgenden Tabelle aufgeführt ist, um products-Ressourcenaufrufe durchzuführen, um einzelne Produkte und Produktpakete einzufügen, abzurufen, zu aktualisieren, aufzulisten und zu löschen.

Wir empfehlen, Versand- und Steuerinformationen auf Kontoebene und nicht auf Produktebene zu konfigurieren.

Bei Mehrfachkunden-Unterkonten von Marktplätzen müssen alle Produkte das Feld external_seller_id enthalten. Weitere Informationen finden Sie unter Produkt-IDs.

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
Titel	Das schwarze Google-T-Shirt	Google-T-Shirt grün	Google Twill Cap
Beschreibung	Das schwarze Google-T-Shirt	Google-T-Shirt aus 100% Baumwolle	Klassische Google-Cap
Artikelgruppen-ID	google_tee	google_tee
Link	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
Bedingung	Neu	Neu	Neu
price	21.99 EUR	21.99 EUR	10.99 EUR
Verfügbarkeit	Auf Lager	Auf Lager	Auf Lager
imageLink	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
gtin [gtin]	9504000059422	9504000059446	9504000059452
mpn	00638NIC	00638ANG	00638ABC
brand	Google	Google	Google
Google-Produktkategorie	Bekleidung & Accessoires > Bekleidung	Bekleidung & Accessoires > Bekleidung	Bekleidung & Accessoires > Bekleidungsaccessoires > Hüte
Farbe	Schwarz	green	Schwarz
Größe	L	M	M
age_group	pornografisch	pornografisch	pornografisch
gender	männlich	männlich	Unisex
included_destination	Shopping Actions, Shopping-Anzeigen	Shopping Actions, Shopping-Anzeigen	Shopping Actions

products.insert

Verwende die folgende Anfrage-URL, um ein einzelnes Produkt einzufügen. Gib dabei deine Händler-ID und einen JSON-Beispieltext an. Mit einer Einfügung wird das neue Produkt erstellt. Wenn für ein bestimmtes Produkt Werte für die Attribute channel, contentLanguage, offerId und feedLabel vorhanden sind, aktualisiert diese Methode diesen Eintrag und ersetzt alle Daten aus vorherigen API-Aufrufen für das jeweilige Produkt.

Produkte, die länger als 7 Tage von allen Zielen ausgeschlossen sind, werden automatisch gelöscht.

Im gezeigten Beispiel wird den verfügbaren Produkten ein neues „Schwarzes Google-T-Shirt“ hinzugefügt.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Beispiel für einen Anfragetext für products.insert:

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

Für ein Produkt können auch benutzerdefinierte Attribute im JSON-Text festgelegt werden. Wir können beispielsweise eine purchase_quantity_limit für ein einzelnes Produkt festlegen, um die Anzahl der Artikel zu begrenzen, die ein Kunde bestellen kann:

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

Das benutzerdefinierte Attribut purchase_quantity_limit legt ein Kauflimit pro Kundenbestellung auf die Produktdefinition fest und wird auch von Feeds unterstützt. Das Attribut befindet sich derzeit in der Betaphase, bis es vollständig von der API unterstützt wird. Zusätzliche benutzerdefinierte Attribute können von einem Händler hinzugefügt werden. Dies führt jedoch nicht zu einer bestimmten Verarbeitung durch die APIs.

Bei einem erfolgreichen Aufruf werden ein HTTP 200-Code und ein Antworttext zurückgegeben, der die eingefügte Produktressource enthält, wobei nur id, offerId, contentLanguage, feedLabel und channel ausgefüllt sind:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

Um Informationen zu einem bestimmten Produkt in der Merchant Center-Datenbank abzurufen, verwenden Sie products.get. Es kann einige Minuten dauern, bis ein neu eingefügtes Produkt über diesen Aufruf verfügbar ist.

Verwende die folgende HTTP-Anfrage-URL und die folgenden Parameter, deine Händler-ID und die Produkt-ID (REST-ID-Format) für das Produkt, das du abrufen möchtest:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Bei einem erfolgreichen Aufruf werden ein HTTP 200 und die „Produktressource“ im Antworttext zurückgegeben. Hier sehen Sie Beispielproduktdaten, die von einem Produkt mit der ID online:en:US:1111111111 abgerufen wurden:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

Verwenden Sie zum Aktualisieren eines einzelnen Produkts die folgende Anfrage-URL mit der PATCH-Methode. Geben Sie dabei Ihre Händler-ID, Ihre Produkt-ID und einen JSON-Text mit den Daten an, die für das Produkt aktualisiert werden sollen. Im Gegensatz zu products.insert, bei dem alle anwendbaren Felder angegeben werden müssen, müssen Sie bei products.update nur die Felder angeben, die Sie ändern möchten.

Hinweis: Das Aktualisieren eines Produkts verhält sich ähnlich wie products.insert und die Verarbeitung der Änderungen kann einige Minuten dauern. Wenn products.update fehlerfrei ist, ist die Aktualisierung erfolgreich. Bei folgenden Aufrufen von products.get wird möglicherweise der vorherige Wert zurückgegeben, bis die Aktualisierung verarbeitet wurde.

Warnung: Mit product.update vorgenommene Änderungen werden nicht beibehalten, wenn das Produkt mit derselben Produkt-ID noch einmal über den Hauptfeed, Subfeed oder die API gesendet wird. Wenn Sie möchten, dass ein Wert auch nach der erneuten Einreichung erhalten bleibt, muss der aktualisierte Wert im Feed oder über den API-Aufruf products.insert enthalten sein.

Wenn Sie ein Attribut hinzufügen oder ändern möchten, geben Sie das Feld mit dem neuen Wert im JSON-Text an. Im gezeigten Beispiel werden title und description eines vorhandenen „Black Google Tee“ mit den Produktdaten im Anfragetext aktualisiert. Alle anderen Felder bleiben unverändert.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Beispiel für einen Anfragetext für products.update:

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

Mit einer products.update-Anfrage können nur Felder der obersten Ebene aktualisiert werden. Wenn Sie verschachtelte Felder aktualisieren möchten, müssen Sie das gesamte Objekt der obersten Ebene angeben.

Im gezeigten Beispiel wird das übergeordnete salePrice-Objekt, einschließlich der verschachtelten Felder eines vorhandenen Produkts, mit den Produktdaten aus dem Anfragetext aktualisiert. Alle anderen Felder bleiben unverändert.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

Wenn Sie bestimmte Felder zum Aktualisieren auswählen möchten, ohne Änderungen an den anderen im Text der Anfrage vorzunehmen, können Sie eine updateMask angeben. Dieser Abfragestringparameter muss eine durch Kommas getrennte Liste der Felder sein, die Sie ändern möchten. Ein updateMask ist nützlich, wenn Sie bestätigen möchten, dass nur die benannten Felder aktualisiert werden. Wenn keine updateMask angegeben wird, entspricht dies dem Markieren aller Felder in der Anfrage, die aktualisiert werden sollen, wie im obigen Beispiel gezeigt.

Im gezeigten Beispiel werden nur die description und availability eines vorhandenen „Black Google Tee“ mit den entsprechenden Produktdaten im Anfragetext aktualisiert. Alle anderen Felder, einschließlich title, bleiben unverändert.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

Beispiel für einen Anfragetext für products.update:

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

Wenn ein Feld in der updateMask-Liste, aber nicht im Text der Anfrage enthalten ist, wird es aus der Product-Ressource gelöscht, sofern vorhanden.

Im gezeigten Beispiel wird updateMask verwendet, um den Wert für das Feld salePrice zu entfernen.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

Der Text der Beispielanfrage sollte das Feld salePrice nicht enthalten, um es zu löschen. Sie können auch keinen Text oder einen leeren Textkörper angeben. Andere Felder bleiben unverändert, sofern sie nicht im updateMask angezeigt werden.

Warnung: Wenn Sie updateMask verwenden, müssen Sie für alle in updateMask aufgeführten Felder den richtigen Wert angeben. Wenn Sie den Wert nicht im Text der Anfrage angeben, entspricht dies dem Löschen des Felds.

Wenn Sie updateMask in einer products.custombatch-Anfrage verwenden möchten, muss updateMask im Text der Anfrage angegeben werden.

Im gezeigten Beispiel werden price und availability eines vorhandenen „Black Google Tee“ mit products.custombatch mit den Produktdaten aus dem Batcheintrag aktualisiert. Alle anderen Felder, einschließlich title und description, bleiben unverändert.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

Wenn du ein einzelnes Produkt löschen möchtest, verwende products.delete mit der Beispiel-HTTP-Anfrage-URL, deiner Händler-ID und der Produkt-ID (im REST-ID-Format wie online:en:US:1111111111) für das Produkt, das du löschen möchtest:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Bei einer erfolgreichen Antwort wird ein HTTP Status 204 ohne Antworttext zurückgegeben.

products.list

products.list listet alle Produkte eines Händlers in der Merchant Center-Datenbank auf. Verwenden Sie die folgende Anfrage-URL:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Bei einem erfolgreichen Aufruf werden ein HTTP 200 und JSON-Daten für Produkte im Ressourcenschlüssel zurückgegeben.

Die folgenden drei Beispielprodukte werden zurückgegeben:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}