Gestire il batching delle regioni

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 insiemi di codici postali o, in alcuni paesi, utilizzando i target geografici predefiniti. Per saperne di più, consulta Configura 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 soluzione è ideale per i commercianti che gestiscono prezzi e disponibilità a livello regionale (RAAP) su larga scala, in quanto migliora l'efficienza e semplifica 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
  • Elimina più regioni contemporaneamente: regions:batchDelete
  • Aggiorna più regioni contemporaneamente: regions:batchUpdate

Prerequisiti

Tutte le richieste batch richiedono il ruolo utente ADMIN per l'autenticazione.

Crea più regioni

Questo esempio mostra come creare due nuove regioni, una definita dai codici postali e l'altra dal targeting geografico, in una singola chiamata di BatchCreateRegions.

Richiesta

Crea l'URL della richiesta come segue:

POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchCreate

Il corpo della richiesta contiene un elenco di requests, in cui 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
    }
  ]
}

L'esempio seguente mostra come creare più regioni in una richiesta batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.CreateRegionRequest;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea.PostalCodeRange;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to create multiple regions for a Merchant Center account. */
public class BatchCreateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  public static void batchCreateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the regions.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<CreateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            CreateRegionRequest.newBuilder()
                .setParent(parent)
                .setRegionId(regionId)
                .setRegion(
                    Region.newBuilder()
                        .setDisplayName("Region " + regionId)
                        .setPostalCodeArea(
                            PostalCodeArea.newBuilder()
                                .setRegionCode("US")
                                .addPostalCodes(
                                    PostalCodeRange.newBuilder()
                                        .setBegin("10001")
                                        .setEnd("10282")
                                        .build())
                                .build())
                        .build())
                .build());
      }

      BatchCreateRegionsRequest request =
          BatchCreateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Create Regions request");
      BatchCreateRegionsResponse response = regionsServiceClient.batchCreateRegions(request);
      System.out.println("Inserted Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to create.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchCreateRegions(config, regionIds);
  }
}

Aggiorna 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 target.

Richiesta

Crea l'URL della richiesta come segue:

POST https://merchantapi.googleapis.com/accounts/v1/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 corretta 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
    }
  ]
}

L'esempio seguente mostra come aggiornare più regioni in una richiesta batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import com.google.shopping.merchant.accounts.v1.UpdateRegionRequest;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to update multiple regions for a Merchant Center account. */
public class BatchUpdateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchUpdateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to update the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<UpdateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            UpdateRegionRequest.newBuilder()
                .setRegion(
                    Region.newBuilder()
                        .setName(getRegionName(accountId, regionId))
                        .setDisplayName("Updated Region " + regionId)
                        .build())
                .setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build())
                .build());
      }

      BatchUpdateRegionsRequest request =
          BatchUpdateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Update Regions request");
      BatchUpdateRegionsResponse response = regionsServiceClient.batchUpdateRegions(request);
      System.out.println("Updated Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to update.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchUpdateRegions(config, regionIds);
  }
}

Elimina più regioni

Puoi eliminare più regioni in una singola chiamata.

Richiesta

Questo esempio mostra come utilizzare BatchDeleteRegions per eliminare due regioni in una singola chiamata.

POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchDelete

Il corpo della richiesta contiene un elenco di requests, in cui ogni oggetto specifica il 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).

{}

L'esempio seguente mostra come eliminare più regioni in una richiesta batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchDeleteRegionsRequest;
import com.google.shopping.merchant.accounts.v1.DeleteRegionRequest;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to delete multiple regions for a Merchant Center account. */
public class BatchDeleteRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchDeleteRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to delete the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<DeleteRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            DeleteRegionRequest.newBuilder().setName(getRegionName(accountId, regionId)).build());
      }

      BatchDeleteRegionsRequest request =
          BatchDeleteRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Delete Regions request");
      regionsServiceClient.batchDeleteRegions(request);
      System.out.println("Regions deleted successfully");

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to delete.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchDeleteRegions(config, regionIds);
  }
}

Limitazioni

Prima di iniziare, tieni presente queste regole:

  • Operazioni atomiche: le richieste batch sono atomiche. Se una singola operazione all'interno del batch non va a buon fine (ad esempio, non viene creata una regione), l'intero batch non andrà a buon fine e non verranno apportate modifiche. L'API restituirà un errore che descrive la causa dell'errore.
  • Limiti dei batch: ogni richiesta batch può contenere un massimo di 100 operazioni per regione.
  • Quote: questi endpoint utilizzano gli stessi gruppi di quote delle loro controparti per singola operazione (regions.create, regions.delete, regions.update).

Errori e problemi comuni

Ecco alcuni errori comuni e le relative soluzioni.

"The number of requests in a batch is too large"

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, suddividi le operazioni in più richieste batch di massimo 100 elementi.

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"
    }
  ]
}

"Region with specified ID already exists"

Si verifica un errore se provi a 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 entrino in conflitto con le regioni esistenti.

"Valore duplicato trovato per il campo region.name o regionId"

Se provi a creare o aggiornare più regioni con lo stesso ID all'interno di una singola richiesta batch, si verifica un errore.

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 comportamento è 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.

Indietro
Create and update regions