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

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

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

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

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

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

برای دستورالعمل‌های مربوط به دانلود و نصب کتابخانه مشتری و استفاده از نمونه‌های کد از GitHub، به Google Merchant API Python Samples مراجعه کنید.

مرحله 3. به عنوان یک توسعه دهنده ثبت نام کنید

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

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

با اختصاص نقش API developer به یک کاربر، یک مخاطب فنی برای حساب Merchant Center شما ایجاد می کند. این به Google امکان می‌دهد به‌روزرسانی‌های مهم را به‌طور خاص درباره 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

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

هنگام ثبت نام:

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

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

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

نقش API_DEVELOPER برای دریافت اعلان‌های مهم لازم است، اما حداقل مجوزها را در Merchant Center دارد. برای اینکه این کاربر بتواند تماس‌های API دیگری انجام دهد یا تنظیمات را در رابط کاربری Merchant Center مدیریت کند، باید نقش‌های دیگری مانند 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 بدهید.

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

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

پایتون

# -*- 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 مشاهده کنید. برای اطلاعات بیشتر، نحوه یافتن برگه منابع داده را ببینید.

مرحله 6. یک محصول را وارد کنید

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

پایتون

# -*- 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. محصولات خود را فهرست کنید

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

پایتون

# -*- 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. به عنوان یک توسعه دهنده ثبت نام کنید

پایتون

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

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

پایتون

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

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

پایتون

مرحله 6. یک محصول را وارد کنید

پایتون

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

پایتون

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