Library klien

Dalam pendekatan untuk berinteraksi dengan Merchant API ini, Anda menggunakan library bawaan yang merangkum detail tingkat rendah dalam membuat permintaan dan menangani respons, sehingga menawarkan cara yang lebih mudah dan sering kali sesuai dengan bahasa untuk berinteraksi dengan API. Library ini menangani autentikasi, serialisasi/deserialisasi permintaan dan respons, serta kode boilerplate lainnya.

Langkah 1. Menyiapkan autentikasi dan mengonfigurasi contoh kode

Untuk mengetahui petunjuknya, lihat Menyiapkan Autentikasi dan Contoh Konfigurasi Contoh untuk Merchant API.

Langkah 2. Mendownload dan menginstal library klien dan contoh kode

Untuk mengetahui petunjuk tentang cara mendownload dan menginstal library klien serta menggunakan contoh kode dari GitHub, lihat Contoh Python Google Merchant API.

Catatan: Contoh kode dan petunjuk terkait tersedia untuk beberapa bahasa pemrograman. Panduan ini memberikan petunjuk dan contoh untuk Python.

Langkah 3. Daftarkan diri sebagai pengembang

Untuk menggunakan Merchant API, Anda harus mendaftarkan informasi kontak developer Anda.

Pendaftaran akan melakukan hal berikut:

• Membuat kontak teknis untuk akun Merchant Center Anda dengan menetapkan peran API developer kepada pengguna. Dengan demikian, Google dapat mengirimkan update penting khusus tentang API dan fitur yang digunakan developer, seperti pengumuman layanan dan informasi tentang fitur baru, yang mungkin kurang menarik bagi non-developer.
• Memungkinkan Anda menggunakan beberapa akun penjual tanpa harus mendaftar beberapa kali. Saat Anda mendaftar, ID project Google Cloud yang digunakan untuk mengautentikasi ke Merchant API dikaitkan dengan akun Merchant Center Anda, yang memiliki kontak teknis (API developer). Dengan cara ini, Anda dapat memperoleh info terbaru penting untuk semua akun penjual yang Anda kelola selama autentikasi dilakukan dengan project Google Cloud yang terdaftar.

Saat mendaftar, perhatikan prasyarat dan batasan yang dijelaskan di Pendaftaran.

Untuk contoh cara mendaftarkan project menggunakan library klien, lihat contoh Mendaftarkan project Google Cloud, dengan memberikan alamat email developer menggunakan 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

Langkah 4. Mengelola kontak dan izin developer

Saat Anda mendaftar:

• Jika alamat email tersebut milik pengguna di akun Merchant Center, pengguna tersebut akan diberi peran API_DEVELOPER.
• Jika alamat email bukan milik pengguna yang ada, undangan akan dikirim ke alamat tersebut. Penerima harus menerima undangan untuk ditambahkan sebagai pengguna baru dengan peran API_DEVELOPER.

Setelah pendaftaran awal, sebaiknya tambahkan beberapa developer dan beri mereka hak akses tambahan.

Langkah 4a. Memberikan izin tambahan

Peran API_DEVELOPER diperlukan untuk menerima notifikasi penting, tetapi memiliki izin minimal dalam Merchant Center. Untuk mengizinkan pengguna ini melakukan panggilan API lain atau mengelola setelan di UI Merchant Center, Anda perlu memberikan peran tambahan kepada pengguna tersebut, seperti STANDARD atau ADMIN. Untuk mengetahui informasi selengkapnya, lihat Jenis akses.

Anda dapat memperbarui hak akses pengguna dengan metode accounts.users.patch.

Contoh kode menunjukkan cara memperbarui pengguna untuk memberikan peran ADMIN dan API_DEVELOPER kepada mereka. Dengan begitu, mereka dapat mengelola akun sepenuhnya dan akan menerima komunikasi terkait 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

Langkah 4b. Menambahkan developer cadangan

Untuk mencegah terganggunya akses API Anda jika kontak developer utama Anda keluar dari organisasi, Anda harus menambahkan setidaknya satu developer cadangan.

Perhatian: Jika pengguna terakhir dengan peran API_DEVELOPER dihapus dari akun Merchant Center Anda, panggilan API Anda akan diblokir setelah masa tenggang 30 hari. Selama periode ini, admin akun akan menerima peringatan melalui email.

Anda dapat menambahkan pengguna dengan metode accounts.users.create atau memperbarui pengguna yang sudah ada dengan metode accounts.users.patch. Sebaiknya berikan pengguna ini peran ADMIN dan API_DEVELOPER.

Langkah 5. Membuat sumber data produk utama

Sebelum dapat menyisipkan produk, Anda memerlukan sumber data produk utama. Untuk kode contoh yang membuat sumber data, lihat Membuat sumber data produk utama yang mendukung beberapa bahasa dengan contoh 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

Anda dapat melihat sumber data ini di UI Merchant Center. Untuk mengetahui informasi selengkapnya, lihat Cara menemukan tab Sumber data.

Langkah 6. Masukkan produk

Setelah membuat sumber data, coba sisipkan produk ke dalamnya. Untuk contoh kode yang menunjukkan cara melakukannya dengan library klien, lihat Menyisipkan contoh input produk dengan 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

Langkah 7. Mencantumkan produk Anda

Untuk kode contoh yang mencantumkan produk di sumber data Anda, lihat Contoh mencantumkan produk dengan 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