فراخوانی‌های مستقیم میانای برنامه‌سازی کاربردی

در این رویکرد برای تعامل با Merchant API، درخواست‌های خام مستقیماً به نقاط پایانی API، معمولاً ازطریق HTTP(S)، ارسال می‌شود. جنبه‌هایی مانند تشکیل بدنه درخواست، تنظیم سرایندها (ازجمله اصالت‌سنجی)، و تجزیه پاسخ را به‌صورت دستی مدیریت می‌کنید.

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

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

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

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

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

برای ثبت‌نام بااستفاده از روش developerRegistration.registerGcp می‌توانید با این نمونه شروع کنید و {DEVELOPER_EMAIL} را با نشانی ایمیل مناسب در بدنه درخواست جایگزین کنید.

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  "developerEmail": "{DEVELOPER_EMAIL}"
}

فراخوانی موفقیت‌آمیز منبع DeveloperRegistration را برمی‌گرداند که پیوند بین پروژه و حسابتان را تأیید می‌کند.

{
  "name": "accounts/{ACCOUNT_ID}/developerRegistration",
  "gcpIds": [
    "123456789012345"
  ]
}

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

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

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

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

مرحله ۲الف. اعطای اجازه‌های بیشتر

نقش API_DEVELOPER برای دریافت اعلان‌های مهم لازم است، اما حداقل اجازه‌ها را در Merchant Center دارد. برای اینکه این کاربر بتواند تماس‌های دیگر با «میانای برنامه‌سازی کاربردی» برقرار کند یا تنظیمات را در Merchant Center UI مدیریت کند، باید نقش‌های دیگری مثل STANDARD یا ADMIN به او اعطا کنید. برای اطلاعات بیشتر، انواع دسترسی را ببینید.

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

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

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/users/{DEVELOPER_EMAIL}?update_mask=access_rights

{
  "access_rights": [
    "ADMIN",
    "API_DEVELOPER"
  ]
}

مرحله ۲ب. افزودن توسعه‌دهندگان پشتیبان

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

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

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

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

POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources

{
  "primaryProductDataSource": {
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "feedLabel": "US"
  },
  "name": "primary-data-source",
  "displayName": "Primary Products Data Source"
}

{ACCOUNT_ID} را با شناسه حساب Merchant Center که ایجاد کرده‌اید جایگزین کنید.

پس‌از اجرای موفقیت‌آمیز این درخواست، باید پاسخ زیر را ببینید:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "Primary Products Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

مقدار فیلد name را کپی کنید. برای درج محصول به آن نیاز خواهید داشت.

می‌توانید این منبع داده را در میانای کاربری Merchant Center مشاهده کنید. برای اطلاعات بیشتر، نحوه پیدا کردن برگه «منابع داده» را ببینید.

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

وقتی منبع داده را ایجاد کردید، سعی کنید محصولی را در آن درج کنید. دستور زیر را اجرا کنید و ACCOUNT_ID صحیح را ارائه دهید. {DATASOURCE_NAME} را با مقداری که قبلاً کپی کرده‌اید جایگزین کنید.

POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE_NAME}
{
  "contentLanguage": "en",
  "feedLabel": "US",
  "name": "Red T-shirt",
  "productAttributes": {
    "gender": "MALE",
    "brand": "New brand"
  },
  "offerId": "tshirt-123"
}

پس‌از اجرای موفقیت‌آمیز این درخواست، باید پاسخ زیر را ببینید:

{
  "name": "accounts/{ACCOUNT_ID}/productInputs/en~US~tshirt-123",
  "product": "accounts/{ACCOUNT_ID}/products/en~US~tshirt-123",
  "offerId": "tshirt-123",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "brand": "New brand",
    "gender": "MALE"
  }
}

شناسه محصول برای محصول جدیداً ایجادشده en~US~tshirt-123 است. می‌توانید از روش accounts.products.get برای بازیابی جزئیات مربوط به این محصول استفاده کنید. همچنین می‌توانید از Merchant Center UI برای مشاهده این محصول استفاده کنید. برای اطلاعات بیشتر درباره مشاهده داده‌های محصول، نمای کلی محصولات در Merchant Center را ببینید.