تم إيقاف الإصدار التجريبي v1 من Merchant API نهائيًا في 28 فبراير 2026. للاطّلاع على خطوات الانتقال إلى أحدث إصدار ثابت، يُرجى قراءة مقالة نقل البيانات من الإصدار التجريبي 1 إلى الإصدار 1.

مكتبات العملاء

في هذا النهج للتفاعل مع Merchant API، يمكنك استخدام المكتبات الجاهزة التي تتضمّن التفاصيل الأساسية لتقديم الطلبات والتعامل مع الردود، ما يوفّر طريقة أكثر ملاءمة وغالبًا ما تكون متوافقة مع اللغة للتفاعل مع واجهة برمجة التطبيقات. تتولّى هذه المكتبات عملية المصادقة وتسلسل/إلغاء تسلسل الطلبات والردود ورمز النص النموذجي الآخر.

الخطوة 1. إعداد المصادقة وتعديل نماذج التعليمات البرمجية

لمعرفة التعليمات، يُرجى الاطّلاع على مقالة إعداد المصادقة ونماذج إعداد العيّنات لـ Merchant API.

الخطوة 2. تنزيل مكتبة البرامج ونماذج التعليمات البرمجية وتثبيتهما

للحصول على تعليمات حول تنزيل مكتبة البرامج وتثبيتها واستخدام نماذج التعليمات البرمجية من GitHub، يُرجى الاطّلاع على مقالة نماذج Python لـ Google Merchant API Samples.

الخطوة 3: التسجيل كمطور برامج

لاستخدام Merchant API، يجب تسجيل معلومات الاتصال الخاصة بالمطوّر.

يؤدي التسجيل إلى ما يلي:

إنشاء جهة اتصال فنية لحسابك على Merchant Center من خلال منح دور API developerلمستخدم ما يتيح لشركة Google إرسال تعديلات مهمة على وجه التحديد حول واجهة برمجة التطبيقات والميزات التي يستخدمها المطوّر، مثل إعلانات الخدمة ومعلومات حول الميزات الجديدة، والتي قد تكون أقل أهمية للمستخدمين غير المطوّرين
السماح لك بالعمل مع حسابات تجارية متعددة بدون الحاجة إلى التسجيل عدة مرات عند التسجيل، يتم ربط رقم تعريف مشروع Google Cloud المستخدَم للمصادقة على Merchant API بحسابك على Merchant Center، الذي يتضمّن جهات الاتصال الفنية (API developers). بهذه الطريقة، يمكنك الحصول على تعديلات مهمة لجميع حسابات التاجر التي تديرها طالما تم إجراء المصادقة باستخدام مشروع على السحابة الإلكترونية المسجَّل من Google.

عند التسجيل، يُرجى مراعاة المتطلبات الأساسية والقيود المفصّلة في صفحة التسجيل.

للاطّلاع على مثال حول كيفية تسجيل مشروعك باستخدام مكتبات البرامج، يُرجى الاطّلاع على نموذج Python : تسجيل مشروع على Google Cloud وتقديم عنوان بريد إلكتروني للمطوّر:

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

الخطوة 4: إدارة جهات اتصال المطوّرين والأذونات

عند التسجيل:

إذا كان عنوان البريد الإلكتروني يعود إلى مستخدم في حساب Merchant Center، يتم منح هذا المستخدم دور API_DEVELOPER.
إذا كان عنوان البريد الإلكتروني لا يعود إلى مستخدم حالي، يتم إرسال دعوة إلى هذا العنوان. على المستلِم قبول الدعوة ليتم إضافته كمستخدم جديد لديه دور API_DEVELOPER.

بعد التسجيل الأولي، ننصحك بإضافة عدة مطوّرين ومنحهم حقوق وصول إضافية.

الخطوة 4أ. منح أذونات إضافية

دور API_DEVELOPER مطلوب لتلقّي الإشعارات المهمة، ولكنّه يمنح الحد الأدنى من الأذونات في Merchant Center. للسماح لهذا المستخدم بإجراء طلبات أخرى من واجهة برمجة التطبيقات أو إدارة الإعدادات في واجهة مستخدم Merchant Center، عليك منحه أدوارًا إضافية، مثل STANDARD أو ADMIN. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع الوصول.

يمكنك تعديل حقوق وصول المستخدم باستخدام الطريقة accounts.users.patch.

يوضّح نموذج التعليمات البرمجية كيفية تعديل مستخدم لمنحه دورَي ADMIN وAPI_DEVELOPER. يسمح له ذلك بإدارة الحساب بالكامل، ما يعني أنّه سيتلقّى أيضًا مراسلات متعلقة بواجهة برمجة التطبيقات.

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

الخطوة 4ب. إضافة مطوّرين احتياطيين

لمنع انقطاع إمكانية وصولك إلى واجهة برمجة التطبيقات في حال مغادرة جهة اتصال المطوّر الأساسية لمؤسستك، عليك إضافة مطوّر احتياطي واحد على الأقل.

يمكنك إضافة مستخدم باستخدام طريقة accounts.users.create أو تعديل مستخدم حالي باستخدام طريقة accounts.users.patch. ننصحك بمنح هذا المستخدم دورَي ADMIN وAPI_DEVELOPER.

الخطوة 5: إنشاء مصدر بيانات أساسي للمنتجات

قبل أن تتمكّن من إدراج منتج، تحتاج إلى مصدر بيانات أساسي للمنتجات. للاطّلاع على رمز نموذجي ينشئ مصدر بيانات، يُرجى الاطّلاع على نموذج 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

يمكنك الاطّلاع على مصدر البيانات هذا في واجهة مستخدم Merchant Center. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة كيفية العثور على علامة التبويب "مصادر البيانات".

الخطوة السادسة. إدراج منتج

بعد إنشاء مصدر البيانات، حاوِل إدراج منتج فيه. للاطّلاع على نموذج تعليمات برمجية يوضّح كيفية إجراء ذلك باستخدام مكتبات البرامج، يُرجى الاطّلاع على نموذج 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

الخطوة 7: عرض قائمة بمنتجاتك

للاطّلاع على رمز نموذجي يعرض قائمة بالمنتجات في مصدر البيانات، يُرجى الاطّلاع على نموذج 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

مكتبات العملاء تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الخطوة 1. إعداد المصادقة وتعديل نماذج التعليمات البرمجية

الخطوة 2. تنزيل مكتبة البرامج ونماذج التعليمات البرمجية وتثبيتهما

الخطوة 3: التسجيل كمطور برامج

Python

الخطوة 4: إدارة جهات اتصال المطوّرين والأذونات

الخطوة 4أ. منح أذونات إضافية

Python

الخطوة 4ب. إضافة مطوّرين احتياطيين

الخطوة 5: إنشاء مصدر بيانات أساسي للمنتجات

Python

الخطوة السادسة. إدراج منتج

Python

الخطوة 7: عرض قائمة بمنتجاتك

Python

مكتبات العملاء