روابط إجراءات الموقع

أدِر أزرار الإجراءات الخاصة بموقع على Google (الطلب، والتوصيل، واستلام الطلبات، وحجز الطاولات، وحجز المواعيد) من خلال Listings API.

روابط إجراءات الموقع هي أزرار الإجراءات التي تعرضها Google في الملف التجاري للنشاط: اطلب عبر الإنترنت، واطلب التوصيل، واحجز طاولة، واحجز موعدًا، وما إلى ذلك. تديرها Listings API بوصفها جزءًا من موقع، لذا يمكنك تعيينها من خلال نقطتي نهاية الإنشاء والتحديث اللتين تستخدمهما بالفعل، واسترجاعها عبر كل نقطة نهاية لقراءة المواقع.

الحقل placeActionLinks

تقبل عمليتا الإنشاء والتحديث مصفوفة placeActionLinks ضمن input. كل عنصر:

القيم الصالحة لـ placeActionType:

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

كيفية مطابقة الرابط (للتعديل / الحذف): باستخدام name إن وُجد، وإلا فباستخدام placeActionType + uri. أدرج name عندما يكون متاحًا لديك (من عملية قراءة) للحصول على أدق مطابقة. الرابط المضاف حديثًا الذي لم يُزامَن مع Google بعد لا يحتوي على name، لذا يُطابَق باستخدام placeActionType + uri.

الإجراءات

نموذج الكتابة هو append/upsert، وليس الاستبدال. عند التحديث، تتأثر فقط الروابط التي تشير إليها؛ وتبقى الروابط التي لا تدرجها دون تغيير.

لتغيير عنوان URL لرابط، أزل الرابط القديم وأضف الرابط الجديد في الطلب نفسه (انظر تغيير عنوان URL لرابط).

مسارات العمل الموصى بها

هناك طريقتان مدعومتان لإضافة روابط إجراءات الموقع والحفاظ على مزامنتها مع Google.

المسار 1: الإنشاء في Google أولًا، ثم الربط

1. يُعِدّ التاجر روابط إجراءات الموقع مباشرةً في Google Business Profile الخاص به.
2. يُربط ذلك الموقع في Google Business Profile بـ Listings API.
3. عند الربط، تسترجع Listings API الروابط الحالية من Google وتضيفها إلى مجموعة الروابط التي تديرها للموقع. لا تحتاج إلى إعادة إدخالها من خلال API.

المسار 2: الإنشاء في Listings API أولًا، ثم الربط

1. أنشئ الموقع في Listings API مع روابط إجراءاته (إنشاء موقع)، أو أضفها لاحقًا (تحديث موقع).
2. عند الربط بـ Google Business Profile، تجلب Listings API الروابط الحالية وتدمجها مع مجموعة الروابط التي تديرها:
   • تنضم الروابط التي تتطابق دون تعارض إلى مجموعة الروابط المُدارة؛
   • وتُعرض أي روابط موجودة لدى Google لا يمكن دمجها تلقائيًا (أو لم تُدرج بعد في مجموعة الروابط المُدارة) ضمن discoveredPlaceActionLinks لتراجعها.
3. في كل عملية إرسال إلى Google، تعيد Listings API فحص الروابط الحالية. يُضاف إلى discoveredPlaceActionLinks أي رابط جديد يُعثر عليه مباشرةً في Google Business Profile ولا تديره Listings API.

الروابط المكتشفة

الروابط المكتشفة هي روابط إجراءات موقع موجودة في Google Business Profile، ولكنها لا تُدار في Listings API. تُجلب هذه الروابط عبر المسارات المذكورة أعلاه (روابط إضافية يُعثر عليها عند الربط، أو روابط جديدة يُعثر عليها عند إرسال لاحق)، وتُرجعها جميع نقاط نهاية القراءة منفصلةً عن الروابط التي تديرها، ضمن discoveredPlaceActionLinks (بالبنية نفسها لـ placeActionLinks): سرد، وحسب المعرّفات، وحسب رموز المتاجر، وبحث.

{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

تبنّي رابط مكتشف

لبدء إدارة رابط مكتشف، أرسله إلى تحديث موقع مع action: "add"، باستخدام الاستدعاء نفسه المستخدم لإضافة أي رابط (يُحدَّد بواسطة placeActionType + uri). تبقى الروابط الأخرى دون تغيير.

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

بعد ذلك، يظهر الرابط ضمن placeActionLinks ويُزال من discoveredPlaceActionLinks. أما الرابط المكتشف الذي لا تتبنّاه، فيظل مدرجًا فحسب (ويُزال تلقائيًا إذا اختفى لاحقًا من Google)؛ ولا يلزم اتخاذ أي إجراء.

أمثلة

تُرجع كل عملية تحديث مجموعة placeActionLinks الكاملة والحالية للموقع (بما يعكس التغيير). بعد عملية الكتابة مباشرةً، تكون قيمة كلٍّ من name وsubmissionStatus للرابط هي null؛ وتُملأ هاتان القيمتان بمجرد مزامنة الرابط مع Google.

إضافة رابط

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

تغيير عنوان URL لرابط

يتألف تغيير عنوان URL من إزالة الرابط القديم وإضافة الرابط الجديد، في الطلب نفسه. إذا سبقت مزامنة الرابط القديم مع Google، فأدرج name الخاص به في delete للحصول على أدق مطابقة؛ وإلا فسيُستخدم placeActionType + uri.

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

لتغيير isPreferred فقط (مع إبقاء عنوان URL نفسه)، أعد إرسال الرابط مع action: "add" والقيمة الجديدة.

إزالة رابط

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

إنشاء موقع مع روابط

عند الإنشاء، يكون كل رابط جديدًا، لذا تكون القيمة الافتراضية لـ action هي add.

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

ملاحظات

• يُسمح بحد أقصى قدره رابط مفضّل واحد لكل نوع.
• يعكس submissionStatus الخاص بالرابط آخر مزامنة مع Google (success، وfailed، وهكذا)، مع submissionMessage بصيغة مقروءة للبشر.
• لا تطبّق Google روابط إجراءات الموقع إلا على المواقع التي جرى التحقّق منها.