Regionen

Mit dem Dienst regions können Sie geografische Regionen erstellen und verwalten, die Sie sowohl mit den Diensten regionalinventory als auch shippingsettings als Ziele verwenden können. Sie können Regionen als Sammlungen von Postleitzahlen oder in einigen Ländern mit vordefinierten geografischen Ausrichtungen definieren. In dieser Anleitung finden Sie Beispiele dafür, wie Sie die einzelnen Regionstypen definieren und wie Sie eine regionale Preisüberschreibung erstellen. Weitere Informationen zum regions-Dienst, einschließlich aller verfügbaren Methoden und Parameter, finden Sie in der Referenzdokumentation.

Voraussetzungen für Regionen

Wenn Sie eine Region erstellen, wird vom Regions-Dienst ermittelt, ob Sie die Region mit anderen Content API-Diensten verwenden können. Das Antwortobjekt, das für einen erfolgreichen regions.create-Aufruf zurückgegeben wird, enthält zwei boolesche Felder, regionalInventoryEligible und shippingEligible, die angeben, ob Sie die Region mit den Diensten regionalinventory bzw. shippingsettings verwenden können.

regionalInventoryEligible

Damit eine Region für die Verwendung mit dem Dienst regionalinventory infrage kommt, muss sie die folgenden Kriterien erfüllen:

  • Die regionId, die Sie beim Erstellen einer Region angeben, darf nur Ziffern enthalten und muss mindestens 6 Ziffern lang sein.
  • Die Region muss die Mindestanforderungen hinsichtlich geografischer Fläche und Onlinebevölkerung erfüllen.

shippingEligible

Damit eine Region für die Verwendung mit dem Dienst shippingsettings infrage kommt, muss sie die folgenden Kriterien erfüllen:

  • Die Region muss anhand von Postleitzahlen definiert werden.
  • Die Region muss Teil eines Landes sein, das vom shippingsettings-Dienst unterstützt wird.

Beispiele

Hier ist ein vollständiges Codebeispiel, mit dem Sie in Java eine neue Region erstellen können:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package shopping.content.v2_1.samples.regions;

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.services.content.model.Region;
import com.google.api.services.content.model.RegionPostalCodeArea;
import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import shopping.content.v2_1.samples.ContentSample;

/**
 * Creates a region. The region created here can be used with the regional inventory service.
 * Regional availability and pricing lets you provide product availability and variable pricing
 * based on your business presence and the location of your customer base. Regional availability and
 * pricing is available for products advertised through Shopping ads on Google Search, and listed in
 * free listings on the Shopping tab.
 */
public class RegionCreateSample extends ContentSample {
  public RegionCreateSample(String[] args) throws IOException {
    super(args);
  }

  @Override
  public void execute() throws IOException {
    checkNonMCA();

    // Creates a List of Postal Code Area Postal Code Ranges.
    // This allows you to flexibly define regions as combinations of postal code
    // ranges. Each postal code range in the list has its own start and end zip code.
    List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges =
        new ArrayList<RegionPostalCodeAreaPostalCodeRange>();

    // Creates a new postal code range from two postal code values.
    // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)
    RegionPostalCodeAreaPostalCodeRange postalCodeRange =
        new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925");

    // Adds the NY State postal code range into the list of postal code ranges that a postal
    // code area accepts.
    postalCodeRanges.add(postalCodeRange);

    // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code
    // ranges, and the US CLDR territory/country code that the postal code ranges applies to.
    RegionPostalCodeArea postalCodeArea =
        new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US");

    // Creates a region with example values for displayName and postalCodeArea
    Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea);

    // Tries to create the region, and catches any exceptions
    try {
      System.out.println("Creating region");
      Region result =
          content
              .regions()
              .create(this.config.getMerchantId().longValue(), region)
              .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits
              .execute();
      System.out.println("Listing succesfully created region");
      System.out.println(result);
    } catch (GoogleJsonResponseException e) {
      checkGoogleJsonResponseException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    new RegionCreateSample(args).execute();
  }
}

Region anhand von Postleitzahlen erstellen

Mit der Methode regions.create können Sie eine Region erstellen, die als Sammlung von Postleitzahlen definiert ist. Im folgenden Beispiel wird eine neue Region für den US-Bundesstaat Arizona erstellt, indem ein Bereich von Postleitzahlen angegeben wird.

Stellen Sie zum Erstellen der Region eine POST-Anfrage mit der folgenden URL und dem folgenden Anfragetext:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

Es gibt ein festes Limit von 2 MB Daten für regions und shippingsettings pro Merchant Center-Konto. Versand- und Regionseinstellungen werden intern von einem Hauptkonto auf alle zugehörigen Unterkonten kopiert. Bei größeren Hauptkonten kann das Speicherlimit daher schnell erreicht werden. In diesem Fall besteht eine Problemumgehung darin, regions und shippingsettings auf Händler-ID-Ebene zu verwalten. Das Regionskontingent kann nicht über das Limit von 2 MB hinaus erhöht werden.

Region mit geografischen Ausrichtungen erstellen

Für Regionen in Brasilien und Russland können Sie auch die Methode regions.create verwenden, um eine Region als Sammlung von geografischen Ausrichtungen zu erstellen, die vordefinierte geografische Einheiten sind. Beispiele für geografische Targeting-Typen sind Länder, Bundesstaaten, Städte, Stadtteile und Flughäfen. Der Dienst regions unterstützt derzeit jedoch nur den Typ „State“ für Brasilien und den Typ „Region“ für Russland. Wenn Sie eine CSV-Datei mit allen IDs für geografische Ausrichtungen herunterladen möchten, einschließlich der geografischen Ausrichtungen, die mit dem regions-Dienst verwendet werden können, lesen Sie den Artikel Geografische Ausrichtungen. Im folgenden Beispiel wird eine neue Region erstellt, indem die geografischen Targeting-IDs von drei brasilianischen Bundesstaaten angegeben werden.

Stellen Sie zum Erstellen der Region eine POST-Anfrage mit der folgenden URL und dem folgenden Anfragetext:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

Regionen zum Erstellen regionaler Preisüberschreibungen verwenden

Wenn Sie eine Region erstellen, gibt der regions-Dienst ein Antwortobjekt zurück, das eine regionId und zwei eligibility-Statusfelder enthält. Wenn der Wert für regionalInventoryEligible true ist, können Sie mit dem Dienst regionaliventory eine Überschreibung erstellen, mit der ein anderer Preis für die Region festgelegt wird. Im folgenden Beispiel wird eine regionale Preisüberschreibung mit der oben erstellten postleitzahlbasierten Region mit dem regionId-Wert „456789“ erstellt.

Stellen Sie zum Erstellen der Überschreibung eine POST-Anfrage mit der folgenden URL und dem folgenden Anfragebody:

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

{
  “regionId”: "456789"
  “price”: {
    value: “10”
    currency: “USD”
  },
  “availability”: “in stock”
}