Migrer la gestion des régions

Ce guide explique comment migrer votre intégration de RegionsService dans Content API for Shopping vers RegionsService dans la sous-API Accounts.

Le service Regions vous permet de définir des zones géographiques personnalisées pour des cas d'utilisation tels que les prix régionaux et les remplacements de livraison. Vous pouvez utiliser des régions avec des services tels que RegionalInventory et ShippingSettings.

Différences majeures

• Structure de l'API : le service Regions fait désormais partie de la sous-API Accounts dans Merchant API (par exemple, merchantapi.googleapis.com/accounts/v1/...).
• Noms de ressources : Merchant API utilise des noms de ressources (accounts/{account}/regions/{region}) au lieu de paramètres merchant_id et region_id distincts dans le chemin d'accès de l'URL pour les opérations Get, Update et Delete.
• Conformité avec la proposition d'amélioration de l'API : les méthodes de Merchant API suivent des modèles standards de proposition d'amélioration de l'API (par exemple, en utilisant parent pour List/Create, name pour Get/Delete et l'utilisation standard de update_mask).
• Types de wrapper : les champs qui utilisaient auparavant google.protobuf.StringValue ou google.protobuf.BoolValue dans Content API utilisent désormais des champs optional standards dans Merchant API.
• Nouvelles fonctionnalités
  • Merchant API introduit un type RadiusArea dans la ressource Region pour définir des régions en fonction d'un rayon autour d'un point (initialement avec une visibilité TRUST_TESTER).
  • Les méthodes par lot (BatchCreateRegions, BatchUpdateRegions, BatchDeleteRegions) sont disponibles.
• Gestion des erreurs : les codes et messages d'erreur fournissent des commentaires plus spécifiques.

Requêtes

Voici comment les modèles de requête changent :

Élément	Content API for Shopping	Merchant API	Description
Point de terminaison	https://shoppingcontent.googleapis.com	https://merchantapi.googleapis.com	Le domaine de base change.
Chemin d'accès Get	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Merchant API utilise la sous-API accounts et un name de ressource.
Chemin d'accès List	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API utilise parent pour spécifier le compte.
Chemin d'accès Create	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API utilise parent. region_id est un champ dans le corps de la requête.
Chemin d'accès Update	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Le nom de la ressource dans Merchant API fait partie de l'objet region dans le corps.
Chemin d'accès Delete	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Utilise le name de la ressource.

Identifiants

Modifiez votre utilisation des identifiants comme suit :

Élément	Content API for Shopping	Merchant API	Description
Compte	merchant_id (entier)	account (entier, partie de la chaîne name ou parent)	Recherchez l'ID de compte intégré dans la chaîne du nom de la ressource, par exemple accounts/{account}.
Région	region_id (chaîne)	{region} (chaîne, partie de la chaîne name)	Recherchez l'ID de région intégré dans la chaîne du nom de la ressource, par exemple accounts/{account}/regions/{region}.
Nom de la ressource	N'est pas strictement utilisé pour les requêtes.	name: accounts/{account}/regions/{region}	Identifiant standard pour les requêtes Get/Update/Delete.
Nom parent	N'est pas strictement utilisé pour les requêtes.	parent: accounts/{account}	Identifiant standard pour les requêtes List/Create.

Ressources

La structure de la ressource Region présente des modifications mineures :

Élément	Content API for Shopping	Merchant API	Description
Identifiant de ressource	region_id (chaîne), merchant_id (int64)	name (chaîne) : accounts/{account}/regions/{region}	Merchant API utilise un seul champ name comme identifiant de ressource.
display_name	google.protobuf.StringValue	optional string	Type de wrapper supprimé.
radius_area	Non disponible (N/A)	RadiusArea	Ce nouveau type définit les régions par rayon. Inclut region_code, lat_lng, radius, radius_units. Par défaut, la visibilité est limitée.
regional_inventory_eligible	google.protobuf.BoolValue (sortie uniquement)	optional bool (sortie uniquement)	Type de wrapper supprimé.
shipping_eligible	google.protobuf.BoolValue (sortie uniquement)	optional bool (sortie uniquement)	Type de wrapper supprimé.

Méthodes

Modifiez votre utilisation des méthodes comme suit :

Élément	Content API for Shopping	Merchant API	Description
Obtenir une région	GetRegion	GetRegion	La requête utilise name.
Créer une région	CreateRegion	CreateRegion	La requête prend le parent de l'URL, tandis que le corps de la requête inclut l'objet region et le region_id.
Mettre à jour une région	UpdateRegion	UpdateRegion	La requête utilise region (qui doit inclure region.name) et update_mask.
Supprimer une région	DeleteRegion	DeleteRegion	La requête utilise name.
Lister les régions	ListRegions	ListRegions	La requête utilise parent. page_size et page_token le comportement est cohérent.
Créer par lot	N/A	BatchCreateRegions	Il s'agit d'une nouvelle méthode.
Mettre à jour par lot	N/A	BatchUpdateRegions	Il s'agit d'une nouvelle méthode.
Supprimer par lot	N/A	BatchDeleteRegions	Il s'agit d'une nouvelle méthode.

Champs renommés

Élément	Content API for Shopping	Merchant API	Description
ID de compte	merchant_id	account (partie de name ou parent)	Intégré aux chaînes name de la ressource. Cela affecte Region (réponse) et les messages protobuf utilisés pour effectuer des requêtes API, tels que CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest et ListRegionsRequest.
ID de région	region_id	region (partie de name), region_id	Intégré à name pour la plupart, champ region_id distinct dans CreateRegionRequest. Cela affecte Region (réponse) et les messages protobuf utilisés pour effectuer des requêtes API, tels que CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest et ListRegionsRequest.
Nom de la région (sortie)	region_id	name	Le champ d'identifiant principal de la réponse est désormais le name complet de la ressource. Cela affecte Region.
Nom à afficher	display_name	display_name	Le type passe de StringValue à optional string. Cela affecte Region.
Indicateurs d'éligibilité	...eligible	...eligible	Le type passe de BoolValue à optional bool. Cela affecte Region.
Masque de mise à jour	update_mask	update_mask	Chemins d'accès aux champs Region. Cela affecte UpdateRegionRequest.

En savoir plus

• Ressource REST : accounts.regions pour Merchant API
• Guide sur les régions
• Configurer des régions