Listings APIListings API
تسجيل الدخول
POST/api/v4/locations/photos/star

تمييز صور الموقع بنجمة

يضع علامة المفضلة على صورة واحدة أو أكثر من الصور الإضافية لموقع، لمنحها أولوية في العرض على منصات النشر التي تدعم ذلك.

يتطلب مفتاح API. راجع المصادقة لمعرفة تنسيق الترويسة وتدوير المفاتيح.

المعلمات

النص الأساسي

الاسمالنوعمطلوبالوصف
input.locationIdstringمطلوبThe location's Base64-encoded Relay ID the photos belong to.
input.photoIdsarray of stringsمطلوبMedia file IDs to star (as returned by the get-photos or upload endpoints).
input.starredbooleanمطلوب`true` to star the given photos, `false` to unstar them. This flag, not the path, decides what happens: `/star` and `/unstar` behave the same way.

مثال على الطلب

نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": [      "TWVkaWFGaWxlOjU4Nzg5MzI="    ],    "starred": true  }}

الاستجابات

200Photos starred. Returns each affected photo with `starred` set to true; `error` is null on success.
Response
{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzI=",          "databaseId": 5878932,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg",          "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_ef4ffb12.jpg",          "type": "ADDITIONAL",          "starred": true        }      ],      "error": null    }  }}
401Unauthenticated, missing or invalid API key.

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

حالة استخدام: إبراز صورة رئيسية موسمية. بعد رفع صورة جديدة لواجهة المتجر، ميّزها بنجمة لتتصدر معرض الصور على Google والمواقع الأخرى التي تدعم ذلك. مرّر معرّف الوسائط الوارد في استجابة الرفع ضمن photoIds.

حالة استخدام: تنسيق مجموعة صور متسقة للعلامة التجارية. عند إدارة مواقع عديدة، ميّز بنجمة صورًا إضافية من الفئة نفسها (مثل صورة الواجهة الخارجية) في كل موقع للحفاظ على اتساق معرض الصور المعروض للجمهور.

نقاط تستدعي الانتباه.

  • تستخدم الاستجابة المفتاح starUnstarLocationPhotos، ولا يُسمّى المفتاح باسم المسار، وهو نفسه في كلٍّ من /locations/photos/star و/locations/photos/unstar.
  • تتضمن حمولة الاستجابة كائن error واحدًا، وليس مصفوفة errors، ولا يوجد clientMutationId. ولا يوجد حقل caption في الصورة أيضًا.
  • لا يمكن تمييز سوى الصور من فئة ADDITIONAL بنجمة. صور LOGO وCOVER أساسية بالفعل ولا يمكن تمييزها بنجمة.
  • يمكن أن يحتوي الموقع على 4 صور مميزة بنجمة كحد أقصى؛ ويؤدي تجاوز هذا الحد إلى فشل العملية بالخطأ SY15012. يحتسب التحقق الصور المميزة بنجمة بالفعل بالإضافة إلى الصور الواردة في هذا الطلب، ولا يُطبَّق إلا عندما تكون قيمة starred هي true.
  • لعكس الإجراء، استخدم POST /api/v4/locations/photos/unstar مع starred: false. تحدد قيمة starred ما يحدث، وليس المسار: يؤدي إرسال starred: true إلى /unstar باستخدام POST إلى تمييز الصور بنجمة.
Request
curl -X POST 'https://listingsapi.com/api/v4/locations/photos/star' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "locationId": "TG9jYXRpb246MTgwMDI4OQ==",      "photoIds": [        "TWVkaWFGaWxlOjU4Nzg5MzI="      ],      "starred": true    }  }'
Run in playground