Una regione dell'API Merchant rappresenta una regione geografica che puoi utilizzare come
target correlato alla risorsa accounts.products.regionalInventories. Puoi
definire le regioni come raccolte di codici postali o, in alcuni paesi,
utilizzando geotarget predefiniti. Per ulteriori informazioni, vedi Configurare
le regioni.
L'API Merchant fornisce endpoint batch per la gestione delle regioni, consentendoti di creare, aggiornare ed eliminare fino a 100 regioni in una singola chiamata API. Questa funzionalità è ideale per i commercianti che gestiscono prezzi e disponibilità a livello regionale (RAAP) su larga scala, migliorando l'efficienza e semplificando l'integrazione.
Panoramica
L'API Batch ti consente di eseguire le seguenti operazioni con i metodi associati:
- Crea più regioni in un'unica richiesta:
regions:batchCreate - Eliminare più regioni contemporaneamente:
regions:batchDelete - Aggiorna più regioni contemporaneamente:
regions:batchUpdate
Prerequisiti
Tutte le richieste batch richiedono il ruolo utente ADMIN per l'autenticazione.
Creare più regioni
Questo esempio mostra come creare due nuove regioni, una definita dai codici postali
e l'altra dal geotargeting, in una singola chiamata di BatchCreateRegions.
Richiesta
Crea l'URL della richiesta nel seguente modo:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Il corpo della richiesta contiene un elenco di requests, dove ogni oggetto specifica un
regionId e i dati region da creare.
{
"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"
]
}
}
}
]
}
Risposta
Una richiesta riuscita restituisce un elenco dei nuovi oggetti region.
{
"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
}
]
}
Aggiornare più regioni
Questo esempio mostra come utilizzare BatchUpdateRegions per aggiornare displayName
e postalCodeArea per due regioni esistenti. Devi fornire un region.name
per aggiornare la regione di destinazione.
Richiesta
Crea l'URL della richiesta nel seguente modo:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Il corpo della richiesta contiene un elenco di requests. Ogni oggetto deve specificare i dati region da aggiornare. Il campo region.name deve contenere l'ID della
regione da aggiornare, ad esempio "98005". Specifica la risorsa come name anziché
accounts/{ACCOUNT_ID}/regions/name. L'inclusione di updateMask per indicare
i campi da modificare è facoltativa.
{
"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"
}
]
}
Risposta
Una richiesta riuscita restituisce un elenco degli oggetti region aggiornati.
{
"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
}
]
}
Eliminare più regioni
Puoi eliminare più regioni in una sola chiamata.
Richiesta
Questo esempio mostra come utilizzare BatchDeleteRegions per eliminare due regioni in una
singola chiamata.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Il corpo della richiesta contiene un elenco di requests, in cui ogni oggetto specifica l'name (senza "accounts/{ACCOUNT_ID}/regions/") della regione da eliminare.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Risposta
Una richiesta riuscita restituisce un corpo della risposta vuoto, a indicare che le regioni specificate sono state eliminate (o non esistevano).
{}
Limitazioni
Prima di iniziare, tieni presente queste regole:
- Operazioni atomiche: le richieste batch sono atomiche. Se una singola operazione all'interno del batch ha esito negativo (ad esempio, non è possibile creare una regione), l'intero batch avrà esito negativo e non verranno apportate modifiche. L'API restituirà un errore che indica la causa del problema.
- Limiti batch: ogni richiesta batch può contenere un massimo di 100 operazioni regionali.
- Quote: questi endpoint utilizzano gli stessi gruppi di quote delle rispettive controparti a singola operazione (
regions.create,regions.delete,regions.update).
Errori e problemi comuni
Di seguito sono riportati alcuni problemi comuni e le relative soluzioni.
"Il numero di richieste in un batch è troppo elevato"
Questo errore si verifica se il numero di operazioni nell'array di richieste supera il limite di 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Per risolvere il problema, dividi le operazioni in più richieste batch di 100 o meno.
Manca un campo obbligatorio
Questo errore si verifica quando manca un campo obbligatorio. Il messaggio di errore specifica il parametro mancante.
I messaggi di errore sono i seguenti:
- Per
batchCreate:[regionId] Required parameter: regionId - Per
batchUpdate:[region.name] Required field not provided. - Per
batchDelete:[name] Required parameter: name
Per risolvere il problema, verifica che tutti i campi obbligatori siano presenti in ogni operazione. Ad esempio, ogni voce di una richiesta batchUpdate deve includere region.name.
La pubblicazione della seguente richiesta genera un errore:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Esiste già una regione con l'ID specificato"
Si verifica un errore se tenti di creare una regione con un regionId già
esistente.
Il messaggio di errore è [regionId] Region with specified id already exists..
Per risolvere il problema, verifica che tutti i valori regionId siano univoci all'interno del batch e non siano in conflitto con le regioni esistenti.
"Valore duplicato trovato per il campo region.name o regionId"
Si verifica un errore se tenti di creare o aggiornare più regioni con lo stesso ID all'interno di una singola richiesta batch.
Il messaggio di errore è Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Per risolvere il problema, verifica che tutti i valori regionId (per batchCreate) o region.name
(per batchUpdate) siano univoci all'interno di una singola richiesta batch.
"Elemento non trovato"
Quando utilizzi batchUpdate, se una regione specificata nella richiesta non esiste,
l'intero batch non andrà a buon fine e verrà visualizzato un errore 404 NOT_FOUND. Questo è diverso da
batchDelete, che ha esito positivo per le regioni inesistenti.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Per risolvere il problema, verifica che tutte le regioni che stai tentando di aggiornare esistano prima di inviare la richiesta.