نسخه بتای اول API فروشگاه در تاریخ ۲۸ فوریه ۲۰۲۶ متوقف و غیرفعال خواهد شد. برای مراحل انتقال به آخرین نسخه پایدار، به بخش «مهاجرت از نسخه بتای اول به نسخه ۱» مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

کتابخانه‌های کارخواه

در این رویکرد برای تعامل با API فروشنده، شما از کتابخانه‌های از پیش ساخته شده استفاده می‌کنید که جزئیات سطح پایین مربوط به ایجاد درخواست‌ها و مدیریت پاسخ‌ها را کپسوله‌سازی می‌کنند و روشی راحت‌تر و اغلب مبتنی بر زبان برای تعامل با API ارائه می‌دهند. آن‌ها احراز هویت، سریال‌سازی/دی‌سریال‌سازی درخواست و پاسخ و سایر کدهای تکراری را مدیریت می‌کنند.

مرحله ۱. تنظیم احراز هویت و پیکربندی نمونه‌های کد

برای دستورالعمل‌ها، به تنظیم احراز هویت و نمونه‌های پیکربندی نمونه برای API فروشنده مراجعه کنید.

مرحله ۲. دانلود و نصب کتابخانه کلاینت و نمونه‌های کد

برای دستورالعمل‌های دانلود و نصب کتابخانه کلاینت و استفاده از نمونه‌های کد از GitHub، به نمونه‌های پایتون API Merchant گوگل مراجعه کنید.

مرحله ۳. ثبت نام به عنوان توسعه دهنده

برای استفاده از Merchant API، باید اطلاعات تماس توسعه‌دهنده خود را ثبت کنید.

ثبت نام موارد زیر را انجام می دهد:

با اختصاص نقش API developer به یک کاربر، یک مخاطب فنی برای حساب مرکز فروشندگان شما ایجاد می‌کند. این به گوگل اجازه می‌دهد به‌روزرسانی‌های مهم را به‌طور خاص در مورد API و ویژگی‌هایی که توسعه‌دهنده استفاده می‌کند، مانند اطلاعیه‌های خدمات و اطلاعات مربوط به ویژگی‌های جدید، که ممکن است برای افراد غیر توسعه‌دهنده کمتر مورد توجه باشد، ارسال کند.
به شما امکان می‌دهد بدون نیاز به ثبت نام چندین بار، با چندین حساب تجاری کار کنید. هنگام ثبت نام، شناسه پروژه Google Cloud که برای تأیید اعتبار در Merchant API استفاده می‌شود، با حساب Merchant Center شما مرتبط می‌شود که دارای مخاطبین فنی ( API developer ) است. به این ترتیب، مادامی که تأیید اعتبار با پروژه ثبت شده Google Cloud انجام شود، می‌توانید به‌روزرسانی‌های مهم را برای همه حساب‌های تجاری که مدیریت می‌کنید، دریافت کنید.

هنگام ثبت نام، پیش نیازها و محدودیت های ذکر شده در بخش ثبت نام را رعایت کنید.

برای مثالی از نحوه ثبت پروژه خود با استفاده از کتابخانه‌های کلاینت، به ثبت یک پروژه Google Cloud مراجعه کنید و آدرس ایمیل توسعه‌دهنده را با استفاده از نمونه پایتون ارائه دهید :

پایتون

# -*- 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

مرحله ۴. مدیریت مخاطبین و مجوزهای توسعه‌دهنده

وقتی ثبت نام می کنید:

اگر آدرس ایمیل متعلق به کاربری در حساب مرکز فروشندگان باشد، به آن کاربر نقش API_DEVELOPER اعطا می‌شود.
اگر آدرس ایمیل متعلق به کاربر فعلی نباشد، دعوتنامه‌ای به آن آدرس ارسال می‌شود. گیرنده باید دعوتنامه را بپذیرد تا به عنوان کاربر جدید با نقش API_DEVELOPER اضافه شود.

پس از ثبت نام اولیه، توصیه می‌کنیم چندین توسعه‌دهنده اضافه کنید و به آنها حقوق دسترسی بیشتری اعطا کنید.

مرحله ۴a. مجوزهای اضافی اعطا کنید

نقش API_DEVELOPER برای دریافت اعلان‌های مهم مورد نیاز است، اما در مرکز فروشندگان حداقل مجوزها را دارد. برای اینکه به این کاربر اجازه دهید فراخوانی‌های API دیگری انجام دهد یا تنظیمات را در رابط کاربری مرکز فروشندگان مدیریت کند، باید نقش‌های دیگری مانند STANDARD یا ADMIN را به او اعطا کنید. برای اطلاعات بیشتر، به انواع دسترسی مراجعه کنید.

شما می‌توانید حقوق دسترسی یک کاربر را با متد accounts.users.patch به‌روزرسانی کنید.

کد نمونه نشان می‌دهد که چگونه می‌توان یک کاربر را به‌روزرسانی کرد تا هر دو نقش ADMIN و API_DEVELOPER را به او اعطا کرد. این به آنها اجازه می‌دهد تا حساب را به طور کامل مدیریت کنند و به این معنی است که آنها همچنین ارتباطات مرتبط با API را دریافت خواهند کرد.

پایتون

# -*- 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

مرحله 4b. توسعه‌دهندگان پشتیبان را اضافه کنید

برای جلوگیری از اختلال در دسترسی به API شما در صورت ترک سازمان توسط توسعه‌دهنده اصلی، باید حداقل یک توسعه‌دهنده پشتیبان اضافه کنید.

شما می‌توانید با استفاده از متد accounts.users.create یک کاربر اضافه کنید یا با استفاده از متد accounts.users.patch یک کاربر موجود را به‌روزرسانی کنید. توصیه می‌کنیم به این کاربر هر دو نقش ADMIN و API_DEVELOPER را بدهید.

مرحله ۵. ایجاد یک منبع داده اولیه محصولات

قبل از اینکه بتوانید یک محصول را وارد کنید، به یک منبع داده اصلی محصولات نیاز دارید. برای نمونه کدی که یک منبع داده ایجاد می‌کند، به «ایجاد یک منبع داده اصلی محصول که از چندین زبان پشتیبانی می‌کند» مراجعه کنید.

پایتون

# -*- 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

شما می‌توانید این منبع داده را در رابط کاربری مرکز فروشندگان مشاهده کنید. برای اطلاعات بیشتر، به نحوه یافتن تب منابع داده مراجعه کنید.

مرحله ۶. درج محصول

پس از ایجاد منبع داده، سعی کنید یک محصول را در آن وارد کنید. برای نمونه کدی که نحوه انجام این کار را با کتابخانه‌های کلاینت نشان می‌دهد، به درج نمونه ورودی محصول با پایتون مراجعه کنید.

پایتون

# -*- 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

مرحله ۷. محصولات خود را فهرست کنید

برای نمونه کدی که محصولات موجود در منبع داده شما را فهرست می‌کند، به نمونه فهرست محصولات با پایتون مراجعه کنید.

پایتون

# -*- 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

کتابخانه‌های کارخواه با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مرحله ۱. تنظیم احراز هویت و پیکربندی نمونه‌های کد

مرحله ۲. دانلود و نصب کتابخانه کلاینت و نمونه‌های کد

مرحله ۳. ثبت نام به عنوان توسعه دهنده

پایتون

مرحله ۴. مدیریت مخاطبین و مجوزهای توسعه‌دهنده

مرحله ۴a. مجوزهای اضافی اعطا کنید

پایتون

مرحله 4b. توسعه‌دهندگان پشتیبان را اضافه کنید

مرحله ۵. ایجاد یک منبع داده اولیه محصولات

پایتون

مرحله ۶. درج محصول

پایتون

مرحله ۷. محصولات خود را فهرست کنید

پایتون

کتابخانه‌های کارخواه