طلبات البيانات المباشرة من واجهة برمجة التطبيقات

في هذه الطريقة للتفاعل مع Merchant API، يتم إرسال طلبات أولية إلى نقاط نهاية واجهة برمجة التطبيقات مباشرةً، عادةً عبر HTTP(S). يمكنك التعامل يدويًا مع جوانب مثل تشكيل نص الطلب، وإعداد العناوين (بما في ذلك المصادقة)، و تحليل الاستجابة.

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

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

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

  • تنشئ هذه العملية جهة اتصال تقنية لحسابك على Merchant Center من خلال منح دور API developer لمستخدم. يتيح ذلك لـ Google إرسال تحديثات مهمة تتعلّق تحديدًا بواجهة برمجة التطبيقات والميزات التي يستخدمها المطوّر، مثل الإشعارات عن الخدمة والمعلومات حول الميزات الجديدة، والتي قد تكون أقل أهمية لغير المطوّرين.
  • يتيح لك العمل مع حسابات تجّار متعددة بدون الحاجة إلى التسجيل عدة مرات. عند التسجيل، يتم ربط رقم تعريف مشروع 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"
  ]
}

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

عند التسجيل:

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

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

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

يجب أن يكون لديك دور "API_DEVELOPER" لتلقّي الإشعارات المهمة، ولكنّه يمنح الحد الأدنى من الأذونات في Merchant Center. للسماح لهذا المستخدم بإجراء طلبات بيانات من واجهة برمجة التطبيقات أو إدارة الإعدادات في واجهة مستخدم Merchant Center، عليك منحه أدوارًا إضافية، مثل 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"
  ]
}

الخطوة 2 (ب): إضافة مطوّرين احتياطيين

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

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

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

لإدراج منتج، تحتاج إلى مصدر بيانات المنتجات الأساسي. يوضّح الطلب التالي كيفية إنشاء مصدر بيانات يمكنك استخدامه لإضافة منتج إلى حسابك:

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

الخطوة 4: إدراج منتج

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