Bibliothèques clientes

Cette approche d'interaction avec l'API Merchant utilise les bibliothèques prédéfinies qui encapsulent les détails de bas niveau de l'envoi de requêtes et de la gestion des réponses. Elle offre une manière plus pratique et souvent idiomatique d'interagir avec l'API. Ils gèrent l'authentification, la sérialisation/désérialisation des requêtes et des réponses, ainsi que d'autres codes passe-partout.

Étape 1 : Configurer l'authentification et les exemples de code

Pour obtenir des instructions, consultez Configurer l'authentification et exemples de configuration pour l'API Merchant.

Étape 2 : Télécharger et installer la bibliothèque cliente et les exemples de code

Pour savoir comment télécharger et installer la bibliothèque cliente, et comment utiliser les exemples de code de GitHub, consultez Exemples Python de l'API Google Merchant.

Remarque : Des exemples de code et les instructions correspondantes sont disponibles pour plusieurs langages de programmation. Ce guide fournit des instructions et des exemples pour Python.

Étape 3 : S'inscrire comme développeur

Pour utiliser Merchant API, vous devez enregistrer les coordonnées de votre développeur.

L'enregistrement permet d'effectuer les actions suivantes :

• Crée un contact technique pour votre compte Merchant Center en attribuant le rôle API developer à un utilisateur. Cela permet à Google d'envoyer des informations importantes concernant spécifiquement l'API et les fonctionnalités utilisées par le développeur, comme des annonces de service et des informations sur les nouvelles fonctionnalités, qui peuvent être moins intéressantes pour les non-développeurs.
• Vous permet de travailler avec plusieurs comptes marchands sans avoir à vous inscrire plusieurs fois. Lorsque vous vous inscrivez, l'ID du projet Google Cloud utilisé pour l'authentification auprès de l'API Merchant est associé à votre compte Merchant Center, qui contient les contacts techniques (les API developer). Vous pourrez ainsi recevoir des informations importantes pour tous les comptes marchands que vous gérez, à condition que l'authentification soit effectuée avec le projet Google Cloud enregistré.

Lors de l'inscription, respectez les conditions requises et les restrictions détaillées dans la section Inscription.

Pour obtenir un exemple d'enregistrement de votre projet à l'aide de bibliothèques clientes, consultez l'exemple Enregistrer un projet Google Cloud en fournissant une adresse e-mail de développeur à l'aide de Python :

Python

# -*- coding: utf-8 -*-
# Copyright 2025 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.

"""This example registers a GCP project with a developer email."""
from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import DeveloperRegistrationServiceClient
from google.shopping.merchant_accounts_v1 import RegisterGcpRequest


def register_gcp(account_id: str, developer_email: str) -> None:
  """Registers the GCP project used to call the Merchant API with a developer email.

  Args:
    account_id: The ID of your Merchant Center account.
    developer_email: The email address of the developer to register.
  """
  # Get OAuth credentials.
  credentials = generate_user_credentials.main()

  # Create a client to the Developer Registration Service.
  client = DeveloperRegistrationServiceClient(credentials=credentials)

  # The name has the format: accounts/{account}/developerRegistration
  name = f"accounts/{account_id}/developerRegistration"

  # Create the request to register the GCP project.
  request = RegisterGcpRequest(
      name=name,
      developer_email=developer_email,
  )

  # Make the API call and handle potential errors.
  try:
    print("Sending RegisterGcp request:")
    response = client.register_gcp(request=request)
    print("Registered GCP project successfully:")
    print(response)
  except RuntimeError as e:
    print(f"An error occurred: {e}")


if __name__ == "__main__":

  # Your Merchant Center account ID.
  # This can be found in the Merchant Center UI.
  _account_id = configuration.Configuration().read_merchant_info()

  # The developer email to associate with the GCP project.
  _developer_email = "YOUR_EMAIL_HERE"

  register_gcp(_account_id, _developer_email)
register_gcp_sample.py

Étape 4 : Gérer les contacts et les autorisations des développeurs

Lorsque vous vous inscrivez :

• Si l'adresse e-mail appartient à un utilisateur du compte Merchant Center, ce dernier se voit attribuer le rôle API_DEVELOPER.
• Si l'adresse e-mail n'appartient pas à un utilisateur existant, une invitation est envoyée à cette adresse. Le destinataire doit accepter l'invitation pour être ajouté en tant que nouvel utilisateur avec le rôle API_DEVELOPER.

Après l'inscription initiale, nous vous recommandons d'ajouter plusieurs développeurs et de leur accorder des droits d'accès supplémentaires.

Étape 4a. Accorder des autorisations supplémentaires

Le rôle API_DEVELOPER est nécessaire pour recevoir les notifications importantes, mais il dispose d'autorisations minimales dans Merchant Center. Pour autoriser cet utilisateur à effectuer d'autres appels d'API ou à gérer les paramètres dans l'UI Merchant Center, vous devez lui accorder des rôles supplémentaires, tels que STANDARD ou ADMIN. Pour en savoir plus, consultez Types d'accès.

Vous pouvez mettre à jour les droits d'accès d'un utilisateur à l'aide de la méthode accounts.users.patch.

L'exemple de code montre comment mettre à jour un utilisateur pour lui attribuer les rôles ADMIN et API_DEVELOPER. Il pourra ainsi gérer entièrement le compte et recevra également les communications liées aux API.

Python

# -*- coding: utf-8 -*-
# Copyright 2024 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
#
#     http://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.
"""A module to update a user."""


from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.protobuf import field_mask_pb2
from google.shopping.merchant_accounts_v1 import AccessRight
from google.shopping.merchant_accounts_v1 import UpdateUserRequest
from google.shopping.merchant_accounts_v1 import User
from google.shopping.merchant_accounts_v1 import UserServiceClient

FieldMask = field_mask_pb2.FieldMask

_ACCOUNT = configuration.Configuration().read_merchant_info()


def update_user(user_email, user_access_right):
  """Updates a user to make it an admin of the MC account."""

  credentials = generate_user_credentials.main()

  client = UserServiceClient(credentials=credentials)

  # Create user name string
  name = "accounts/" + _ACCOUNT + "/users/" + user_email

  user = User(name=name, access_rights=[user_access_right])

  field_mask = FieldMask(paths=["access_rights"])

  try:
    request = UpdateUserRequest(user=user, update_mask=field_mask)

    print("Sending Update User request")
    response = client.update_user(request=request)
    print("Updated User Name below")
    print(response.name)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # Modify this email to update the right user
  email = "USER_MAIL_ACCOUNT"
  access_right = AccessRight.ADMIN
  update_user(email, access_right)

update_user_sample.py

Étape 4b. Ajouter des développeurs de secours

Pour éviter que votre accès à l'API ne soit interrompu si votre contact principal pour les développeurs quitte votre organisation, vous devez ajouter au moins un développeur de secours.

Attention : Si le dernier utilisateur disposant du rôle API_DEVELOPER est supprimé de votre compte Merchant Center, vos appels d'API seront bloqués après un délai de grâce de 30 jours. Pendant cette période, les administrateurs de compte recevront des avertissements par e-mail.

Vous pouvez ajouter un utilisateur avec la méthode accounts.users.create ou en mettre à jour un existant avec la méthode accounts.users.patch. Nous vous recommandons d'attribuer à cet utilisateur les rôles ADMIN et API_DEVELOPER.

Étape 5 : Créer une source de données produit principale

Avant de pouvoir insérer un produit, vous devez disposer d'une source de données produit principale. Pour obtenir un exemple de code permettant de créer une source de données, consultez Exemple de création d'une source de données produit principale compatible avec plusieurs langues avec Python.

Python

# -*- coding: utf-8 -*-
# Copyright 2024 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
#
#     http://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.
"""This class demonstrates how to create a Primary product datasource all `feedLabel` and `contentLanguage` combinations.

This works only for API primary feeds.
"""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_datasources_v1 import CreateDataSourceRequest
from google.shopping.merchant_datasources_v1 import DataSource
from google.shopping.merchant_datasources_v1 import DataSourcesServiceClient
from google.shopping.merchant_datasources_v1 import PrimaryProductDataSource

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"


def create_primary_product_data_source_multiple_languages():
  """Creates a `DataSource` resource."""

  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = DataSourcesServiceClient(credentials=credentials)

  # Creates a PrimaryProductDataSource.
  primary_datasource = PrimaryProductDataSource()
  primary_datasource.countries = ["GB"]

  # Creates a DataSource and populates its attributes.
  data_source = DataSource()
  data_source.display_name = "Example Multiple Languages Primary DataSource"
  data_source.primary_product_data_source = primary_datasource

  # Creates the request.
  request = CreateDataSourceRequest(parent=_PARENT, data_source=data_source)

  # Makes the request and catches and prints any error messages.
  try:
    response = client.create_data_source(request=request)
    print(f"DataSource successfully created: {response}")
  except RuntimeError as e:
    print("DataSource creation failed")
    print(e)


if __name__ == "__main__":
  create_primary_product_data_source_multiple_languages()

create_primary_product_data_source_multiple_languages_sample.py

Vous pouvez consulter cette source de données dans l'UI Merchant Center. Pour en savoir plus, consultez Comment trouver l'onglet "Sources de données" ?

Étape 6 : Insérer un produit

Une fois la source de données créée, essayez d'y insérer un produit. Pour obtenir un exemple de code montrant comment procéder avec les bibliothèques clientes, consultez Exemple d'insertion d'une entrée de produit avec Python.

Python

# -*- coding: utf-8 -*-
# Copyright 2024 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
#
#     http://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.
"""A module to insert a Product Input."""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping import merchant_products_v1
from google.shopping.merchant_products_v1 import Availability
from google.shopping.merchant_products_v1 import Condition
from google.shopping.type import Price

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"

# You can only insert products into datasource types of Input "API" and
# "FILE", and of Type "Primary" or "Supplemental."
_DATA_SOURCE = "[INSERT_DATA_SOURCE_HERE]"
_DATA_SOURCE_NAME = f"accounts/{_ACCOUNT}/dataSources/{_DATA_SOURCE}"


def create_product_input():
  """Creates a `ProductInput` resource."""

  # Creates a shipping setting
  price = Price()
  price.amount_micros = 33_450_000
  price.currency_code = "GBP"

  shipping_option_1 = merchant_products_v1.Shipping()
  shipping_option_1.price = price
  shipping_option_1.country = "GB"
  shipping_option_1.service = "1st class post"

  price2 = Price()
  price2.amount_micros = 33_450_000
  price2.currency_code = "EUR"

  shipping_option_2 = merchant_products_v1.Shipping()
  shipping_option_2.price = price2
  shipping_option_2.country = "FR"
  shipping_option_2.service = "2nd class post"

  # Sets product attributes. Make sure to replace these values with your own.
  attributes = merchant_products_v1.ProductAttributes()
  attributes.title = "A Tale of Two Cities"
  attributes.description = "A classic novel about the French Revolution"
  attributes.link = "https://exampleWebsite.com/tale-of-two-cities.html"
  attributes.image_link = "https://exampleWebsite.com/tale-of-two-cities.jpg"
  attributes.price = price
  attributes.availability = Availability.IN_STOCK
  attributes.condition = Condition.NEW
  attributes.google_product_category = "Media > Books"
  attributes.gtins = ["9780007350896"]
  attributes.shipping = [shipping_option_1, shipping_option_2]

  return merchant_products_v1.ProductInput(
      content_language="en",
      feed_label="GB",
      offer_id="sku123",
      product_attributes=attributes,
  )


def insert_product_input():
  """Inserts the specified `ProductInput` resource."""

  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = merchant_products_v1.ProductInputsServiceClient(
      credentials=credentials
  )

  # Creates the request.
  request = merchant_products_v1.InsertProductInputRequest(
      parent=_PARENT,
      # If this product is already owned by another datasource, when
      # re-inserting, the new datasource will take ownership of the product.
      product_input=create_product_input(),
      data_source=_DATA_SOURCE_NAME,
  )

  # Makes the request and catches and prints any error messages.
  try:
    response = client.insert_product_input(request=request)
    # The last part of the product name will be the product ID assigned to a
    # product by Google. Product ID has the format
    # `contentLanguage~feedLabel~offerId`
    print(f"Input successful: {response}")
  except RuntimeError as e:
    print("Input failed")
    print(e)
    # After the product is inserted, the product ID will be returned in the
    # response. We recommend that you check the Merchant Center to ensure that
    # the product is approved and visible to users before using the product ID
    # in any downstream processes.


if __name__ == "__main__":
  insert_product_input()

insert_product_input_sample.py

Étape 7 : Présenter vos produits

Pour obtenir un exemple de code qui liste les produits de votre source de données, consultez l'exemple de liste de produits avec Python.

Python

# -*- coding: utf-8 -*-
# Copyright 2024 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
#
#     http://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.
"""A module to list Products."""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping import merchant_products_v1

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"


def list_products():
  """Lists the `Product` resources for a given account."""

  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = merchant_products_v1.ProductsServiceClient(
      credentials=credentials
  )

  # Creates the request. Set the page size to the maximum value.
  request = merchant_products_v1.ListProductsRequest(
      parent=_PARENT, page_size=1000
  )

  # Makes the request and catches and prints any error messages.
  try:
    response = client.list_products(request=request)
    for product in response:
      print(product)
    print("List request successful!")
  except RuntimeError as e:
    print("List request failed")
    print(e)


if __name__ == "__main__":
  list_products()

list_products_sample.py