Questa pagina è stata tradotta dall'API Cloud Translation.

Regioni

Il servizio regions ti consente di creare e gestire regioni geografiche che puoi utilizzare come destinazioni con i servizi regionalinventory e shippingsettings. Puoi definire le regioni come raccolte di codici postali o, in alcuni paesi, utilizzando i target geografici predefiniti. Questa guida fornisce esempi di come definire ogni tipo di regione e di creare una sostituzione dei prezzi a livello di regione. Per ulteriori informazioni sul servizio regions, inclusi tutti i metodi e i parametri disponibili, consulta la documentazione di riferimento.

Idoneità delle regioni

Quando crei una regione, il servizio Regioni determina se puoi utilizzare la regione con altri servizi dell'API Content. L'oggetto di risposta restituito per una chiamata regions.create riuscita include due campi booleani, regionalInventoryEligible e shippingEligible, che indicano se puoi utilizzare la regione con i servizi regionalinventory e shippingsettings rispettivamente.

regionalInventoryEligible

Per essere idonea all'utilizzo con il servizio regionalinventory, una regione deve soddisfare i seguenti criteri:

Il valore regionId, specificato al momento della creazione di una regione, deve contenere solo cifre e almeno 6.
La regione deve soddisfare i requisiti di dimensioni minimi per l'area geografica e la compilazione online.

shippingEligible

Per essere idonea all'utilizzo con il servizio shippingsettings, una regione deve soddisfare i seguenti criteri:

La regione deve essere definita utilizzando i codici postali.
La regione deve far parte di un paese supportato dal servizio shippingsettings.

Campioni

Ecco un esempio di codice completo che puoi utilizzare per creare una nuova regione in Java:

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

Crea una regione utilizzando i codici postali

Puoi utilizzare il metodo regions.create per creare una regione definita come raccolta di codici postali. L'esempio riportato di seguito crea una nuova regione per lo stato americano dell'Arizona specificando un intervallo di codici postali.

Per creare la regione, effettua una richiesta POST con il seguente URL e corpo della richiesta:

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

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

Esiste un limite fisso di 2 MB di dati per regions e shippingsettings per account Merchant Center. Le impostazioni di spedizione e regione vengono copiate internamente da un AMC a tutti i relativi subaccount, quindi, nel caso di AMC di grandi dimensioni, potresti raggiungere rapidamente il limite di spazio di archiviazione. In questo caso, una soluzione alternativa è gestire regions e shippingsettings a livello di ID commerciante. Non c'è modo di aumentare la quota per le regioni oltre il limite di 2 MB.

Creare una regione utilizzando i target geografici

Per le regioni di Brasile e Russia, puoi anche utilizzare il metodo regions.create per creare una regione definita come raccolta di target geografici, ovvero aree geografiche predefinite. Esempi di tipi di target geografici sono paesi, stati, città, quartieri e aeroporti. Tuttavia, al momento il servizio regions supporta solo il tipo "Stato" per il Brasile e il tipo "Regione" per la Russia. Per scaricare un file CSV di tutti gli ID dei target geografici, compresi quelli che possono essere utilizzati con il servizio regions, consulta Target geografici. L'esempio riportato di seguito crea una nuova regione fornendo gli ID targeting geografico di tre stati brasiliani.

Per creare la regione, effettua una richiesta POST utilizzando il seguente URL e il corpo della richiesta:

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

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

Utilizza le regioni per creare sostituzioni di prezzi regionali

Quando crei una regione, il servizio regions restituisce un oggetto di risposta che include un regionId e due campi dello stato di idoneità. Se il valore regionalInventoryEligible è true, puoi utilizzare il servizio regionaliventory per creare un override che imposti un prezzo diverso per la regione. L'esempio riportato di seguito crea una sostituzione di prezzo regionale utilizzando la regione basata sul codice postale creata nell'esempio precedente, che ha un valore regionId di "456789".

Per creare l'override, effettua una richiesta POST utilizzando il seguente URL e il corpo della richiesta:

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

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