Regionen-Batching verwalten

Eine Merchant API-Region ist eine geografische Region, die Sie als Ziel für die Ressource accounts.products.regionalInventories verwenden können. Sie können Regionen als Sammlungen von Postleitzahlen oder in einigen Ländern mithilfe vordefinierter geografischer Ziele definieren. Weitere Informationen finden Sie unter Regionen einrichten.

Die Merchant API bietet Batch-Endpunkte zum Verwalten Ihrer Regionen. Damit können Sie bis zu 100 Regionen in einem einzigen API-Aufruf erstellen, aktualisieren und löschen. Dies ist ideal für Händler, die die Angabe regionaler Preise und Verfügbarkeit in großem Umfang verwalten, da es die Effizienz verbessert und die Integration vereinfacht.

Übersicht

Mit der Batch API können Sie mit den zugehörigen Methoden Folgendes tun:

  • Mehrere Regionen in einer einzelnen 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 zur Authentifizierung erforderlich.

Mehrere Regionen erstellen

In diesem Beispiel wird gezeigt, wie Sie mit einem einzigen Aufruf von BatchCreateRegions zwei neue Regionen erstellen – eine definiert durch Postleitzahlen und eine andere durch geografisches Targeting.

Anfrage

Erstellen Sie die Anfrage-URL so:

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

Im folgenden Beispiel wird gezeigt, wie Sie mehrere Regionen in einer Batchanfrage erstellen:

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);
  }
}

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 einen region.name angeben, um die Zielregion zu aktualisieren.

Anfrage

Erstellen Sie die Anfrage-URL so:

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

Der Anfragetext enthält eine Liste von requests. In jedem 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 und nicht als accounts/{ACCOUNT_ID}/regions/name an. Die Angabe 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

Eine erfolgreiche Anfrage gibt eine Liste der aktualisierten region-Objekte zurück.

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

Im folgenden Beispiel wird gezeigt, wie Sie mehrere Regionen in einer Batchanfrage aktualisieren:

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);
  }
}

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/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchDelete

Der Anfragetext enthält eine Liste von requests, wobei jedes Objekt den 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, was bedeutet, dass die angegebenen Regionen gelöscht wurden (oder nicht vorhanden waren).

{}

Im folgenden Beispiel wird gezeigt, wie Sie mehrere Regionen in einer Batchanfrage löschen:

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);
  }
}

Beschränkungen

Beachten Sie die folgenden Regeln, bevor Sie beginnen:

  • 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.
  • Batchlimits: Jede Batchanfrage kann maximal 100 Regionsvorgänge enthalten.
  • Kontingente: Diese Endpunkte verwenden dieselben Kontingentgruppen wie ihre Gegenstücke für einzelne Vorgänge (regions.create, regions.delete, regions.update).

Häufige Fehler und Probleme

Im Folgenden finden Sie einige häufige Probleme und ihre Lösungen.

„Die Anzahl der Anfragen in einem Batch ist zu groß“

Dieser Fehler tritt auf, wenn die Anzahl der Vorgänge im Array „requests“ das Limit von 100 überschreitet.

"error":
  {
    "code": 400,
    "message": "The number of requests in a batch is too large.",
    "status": "INVALID_ARGUMENT"
  }

Teilen Sie die Vorgänge in mehrere Batchanfragen mit maximal 100 Vorgängen auf, um das Problem zu beheben.

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 erforderlichen Felder in jedem Vorgang vorhanden sind. Beispielsweise muss jeder Eintrag in einer batchUpdate-Anfrage die region.name enthalten. Das Senden der folgenden Anfrage führt zu einem Fehler:

{
  "requests":
  [
    {
      "region":
        {
          "displayName": "An update without a region name"
        },
        "updateMask": "displayName"
    }
  ]
}

„Region mit der angegebenen ID ist bereits vorhanden“

Wenn Sie versuchen, eine Region mit einer bereits vorhandenen regionId zu erstellen, tritt ein Fehler auf.

Die Fehlermeldung lautet [regionId] Region with specified id already exists..

Prüfen Sie, ob alle regionId-Werte innerhalb des Batches eindeutig sind und nicht mit vorhandenen Regionen in Konflikt stehen.

„Doppelter Wert für das Feld ‚region.name‘ oder ‚regionId‘ gefunden“

Wenn Sie versuchen, mehrere Regionen mit derselben ID in einer einzelnen Batchanfrage zu erstellen oder zu aktualisieren, tritt ein Fehler auf.

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) innerhalb 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 dem Fehler 404 NOT_FOUND fehl. Dies unterscheidet sich von batchDelete, das für nicht vorhandene Regionen erfolgreich ist.

"error": {
    "code": 404,
    "message": "item not found",
    "status": "NOT_FOUND"
}

Prüfen Sie vor dem Senden der Anfrage, ob alle Regionen, die Sie aktualisieren möchten, vorhanden sind.