Eine Merchant API-Region ist eine geografische Region, die Sie als Ziel für die accounts.products.regionalInventories-Ressource verwenden können. Sie können Regionen als Sammlungen von Postleitzahlen oder in einigen Ländern mithilfe vordefinierter geografischer Ausrichtungen definieren. Weitere Informationen finden Sie unter Regionen einrichten.
Die Merchant API bietet Batch-Endpunkte zum Verwalten Ihrer Regionen. Damit können Sie mit einem einzigen API-Aufruf bis zu 100 Regionen erstellen, aktualisieren und löschen. Das ist ideal für Händler, die regionale Preise und Verfügbarkeit (Regional Availability and Pricing, RAAP) im großen Maßstab verwalten, da es die Effizienz steigert und die Integration vereinfacht.
Übersicht
Mit der Batch API und den zugehörigen Methoden haben Sie folgende Möglichkeiten:
- Mehrere Regionen in einer einzigen Anfrage erstellen:
regions:batchCreate - Mehrere Regionen gleichzeitig löschen:
regions:batchDelete - Mehrere Regionen gleichzeitig aktualisieren:
regions:batchUpdate
Vorbereitung
Für alle Batchanfragen ist die Nutzerrolle ADMIN für die Authentifizierung erforderlich.
Mehrere Regionen erstellen
In diesem Beispiel wird gezeigt, wie Sie in einem einzelnen Aufruf von BatchCreateRegions zwei neue Regionen erstellen – eine, die durch Postleitzahlen definiert wird, und eine, die durch geografische Ausrichtung definiert wird.
Anfrage
Erstellen Sie die Anfrage-URL so:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Der Anfragetext enthält eine Liste von requests, wobei jedes Objekt einen regionId und die zu erstellenden region-Daten angibt.
{
"requests": [
{
"regionId": "seattle-area-98340",
"region": {
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
}
}
},
{
"regionId": "co-de-states",
"region": {
"displayName": "Colorado and Delaware",
"geoTargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
}
}
}
]
}
Antwort
Bei einer erfolgreichen Anfrage wird eine Liste der neuen region-Objekte zurückgegeben.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
"displayName": "Colorado and Delaware",
"geotargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
},
"regionalInventoryEligible": false,
"shippingEligible": false
}
]
}
Mehrere Regionen aktualisieren
In diesem Beispiel wird gezeigt, wie Sie mit BatchUpdateRegions die displayName und postalCodeArea für zwei vorhandene Regionen aktualisieren. Sie müssen eine region.name angeben, um die Zielregion zu aktualisieren.
Anfrage
Erstellen Sie die Anfrage-URL so:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Der Anfragetext enthält eine Liste von requests. Für jedes Objekt müssen die zu aktualisierenden region-Daten angegeben werden. Das Feld region.name muss die ID der zu aktualisierenden Region enthalten, z. B. „98005“. Geben Sie die Ressource als name an und nicht als accounts/{ACCOUNT_ID}/regions/name. Das Einfügen von updateMask, um die zu ändernden Felder anzugeben, ist optional.
{
"requests": [
{
"region": {
"name": "98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
},
{
"region": {
"name": "07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
}
]
}
Antwort
Bei einer erfolgreichen Anfrage wird eine Liste der aktualisierten region-Objekte zurückgegeben.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
}
]
}
Mehrere Regionen löschen
Sie können mehrere Regionen in einem einzigen Aufruf löschen.
Anfrage
In diesem Beispiel wird gezeigt, wie Sie mit BatchDeleteRegions zwei Regionen in einem einzigen Aufruf löschen.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Der Anfragetext enthält eine Liste von requests, wobei jedes Objekt die name (ohne "accounts/{ACCOUNT_ID}/regions/") der zu löschenden Region angibt.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Antwort
Eine erfolgreiche Anfrage gibt einen leeren Antworttext zurück, der angibt, dass die angegebenen Regionen gelöscht wurden (oder nicht vorhanden waren).
{}
Beschränkungen
Beachten Sie vorab folgende Regeln:
- Atomare Vorgänge: Batchanfragen sind atomar. Wenn ein einzelner Vorgang im Batch fehlschlägt (z. B. wenn eine Region nicht erstellt werden kann), schlägt der gesamte Batch fehl und es werden keine Änderungen vorgenommen. Die API gibt einen Fehler zurück, in dem die Ursache des Fehlers beschrieben wird.
- Batch-Limits: Jede Batchanfrage kann maximal 100 regionale Vorgänge enthalten.
- Kontingente: Diese Endpunkte verwenden dieselben Kontingentgruppen wie ihre Einzelvorgang-Entsprechungen (
regions.create,regions.delete,regions.update).
Häufige Fehler und Probleme
Im Folgenden finden Sie einige häufige Fehler und ihre Lösungen.
„Die Anzahl der Anfragen in einem Batch ist zu groß.“
Dieser Fehler tritt auf, wenn die Anzahl der Vorgänge in Ihrem Anforderungsarray das Limit von 100 überschreitet.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Um dieses Problem zu beheben, teilen Sie Ihre Vorgänge in mehrere Batchanfragen mit jeweils maximal 100 Vorgängen auf.
Ein Pflichtfeld fehlt
Dieser Fehler tritt auf, wenn ein Pflichtfeld fehlt. In der Fehlermeldung wird der fehlende Parameter angegeben.
Die Fehlermeldungen lauten so:
- Für
batchCreate:[regionId] Required parameter: regionId - Für
batchUpdate:[region.name] Required field not provided. - Für
batchDelete:[name] Required parameter: name
Prüfen Sie, ob alle Pflichtfelder in jedem Vorgang vorhanden sind. Beispielsweise muss jeder Eintrag in einer batchUpdate-Anfrage die region.name enthalten.
Wenn Sie die folgende Anfrage senden, wird ein Fehler ausgegeben:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
„Region mit der angegebenen ID ist bereits vorhanden“
Ein Fehler tritt auf, wenn Sie versuchen, eine Region mit einem regionId zu erstellen, das bereits vorhanden ist.
Die Fehlermeldung lautet [regionId] Region with specified id already exists..
Prüfen Sie, ob alle regionId-Werte im Batch eindeutig sind und nicht mit vorhandenen Regionen in Konflikt stehen.
„Doppelter Wert für Feld ‚region.name‘ oder ‚regionId‘ gefunden“
Ein Fehler tritt auf, wenn Sie versuchen, mehrere Regionen mit derselben ID in einer einzelnen Batchanfrage zu erstellen oder zu aktualisieren.
Die Fehlermeldung lautet Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Prüfen Sie, ob alle regionId-Werte (für batchCreate) oder region.name-Werte (für batchUpdate) in einer einzelnen Batchanfrage eindeutig sind.
„Artikel nicht gefunden“
Wenn Sie batchUpdate verwenden und eine in der Anfrage angegebene Region nicht vorhanden ist, schlägt der gesamte Batch mit einem 404 NOT_FOUND-Fehler fehl. Dies unterscheidet sich von batchDelete, das auch für nicht vorhandene Regionen erfolgreich ist.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Prüfen Sie, ob alle Regionen, die Sie aktualisieren möchten, vorhanden sind, bevor Sie die Anfrage senden.