Migrer la gestion des régions

Ce guide explique comment migrer votre intégration depuis 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 exceptions 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 l'API Merchant (par exemple, merchantapi.googleapis.com/accounts/v1/...).
• Noms de ressources : l'API Merchant 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 l'AIP : les méthodes de l'API Merchant suivent les modèles standards de proposition d'amélioration de l'API (par exemple, l'utilisation de parent pour List/Create, de name pour Get/Delete et l'utilisation standard de update_mask).
• Types de wrappers : les champs qui utilisaient auparavant google.protobuf.StringValue ou google.protobuf.BoolValue dans Content API utilisent désormais des champs optional standards dans l'API Merchant.
• Nouvelles fonctionnalités :
  • L'API Merchant 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 informations plus spécifiques.

Requêtes

Voici comment les schémas de requête changent :

Élément	Content API for Shopping	API Merchant	Description
Point de terminaison	https://shoppingcontent.googleapis.com	https://merchantapi.googleapis.com	Le domaine de base change.
Obtenir le chemin d'accès	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	L'API Merchant utilise la sous-API accounts et une ressource name.
Chemin de la liste	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	L'API Merchant utilise parent pour spécifier le compte.
Créer un chemin	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	L'API Merchant utilise parent. region_id est un champ du corps de la requête.
Chemin de mise à jour	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Dans l'API Merchant, le nom de la ressource fait partie de l'objet region dans le corps.
Supprimer le chemin	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Utilise la ressource name.

Identifiants

Modifiez votre utilisation des identifiants comme suit :

Élément	Content API for Shopping	API Merchant	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 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 demandes.	name : accounts/{account}/regions/{region}	Identifiant standard pour les requêtes Get/Update/Delete.
Nom du parent	N'est pas strictement utilisé pour les demandes.	parent : accounts/{account}	Identifiant standard pour les requêtes List/Create.

Ressources

La structure de la ressource Region a subi quelques modifications mineures :

Élément	Content API for Shopping	API Merchant	Description
Identifiant de ressource	region_id (chaîne), merchant_id (int64)	name (chaîne) : accounts/{account}/regions/{region}	L'API Merchant 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 et 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	API Merchant	Description
Obtenir la région	GetRegion	GetRegion	La requête utilise name.
Créer une région	CreateRegion	CreateRegion	La requête extrait le parent de l'URL, tandis que le corps de la requête inclut l'objet region et le region_id.
Modifier la région	UpdateRegion	UpdateRegion	La requête utilise region (qui doit inclure region.name) et update_mask.
Supprimer la région	DeleteRegion	DeleteRegion	La requête utilise name.
Lister les régions	ListRegions	ListRegions	La requête utilise parent. Le comportement de page_size et page_token est cohérent.
Création par lot	N/A	BatchCreateRegions	Il s'agit d'une nouvelle méthode.
Mise à jour groupée	N/A	BatchUpdateRegions	Il s'agit d'une nouvelle méthode.
Suppression par lot	N/A	BatchDeleteRegions	Il s'agit d'une nouvelle méthode.

Champs renommés

Élément	Content API for Shopping	API Merchant	Description
ID de compte	merchant_id	account (partie de name ou parent)	Intégrés aux chaînes de ressources name. Cela affecte Region (réponse) et les messages protobuf utilisés pour envoyer des requêtes d'API, tels que CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest et ListRegionsRequest.
Identifiant de la région	region_id	region (partie de name), region_id	Intégré à name pour la plupart des utilisateurs, champ region_id distinct dans CreateRegionRequest. Cela affecte les messages protobuf Region (réponse) et ceux utilisés pour envoyer des requêtes d'API, tels que CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest et ListRegionsRequest.
Nom de la région (sortie)	region_id	name	Le champ d'identifiant principal dans la réponse est désormais l'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 l'API Merchant
• Guide Régions
• Configurer des régions