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

رفع صور إلى موقع

يُرفق وسائط بموقع، إما باستخدام عنوان URL عام لصورة أو بالإشارة إلى ملفات موجودة بالفعل في مكتبة الوسائط لديك.

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

المعلمات

النص الأساسي

ينطبق الحقل المتداخل المحدد على أنه مطلوب فقط عند إرسال الحقل الأصل. إذا كان الحقل الأصل اختياريًا وحذفته، فلا تنطبق حقوله الفرعية المطلوبة.

الاسمالنوعمطلوبالوصف
input.locationIdstringمطلوبThe location's Base64-encoded Relay ID to attach media to.
input.photosarray of objectsمطلوبImages to attach. `photo` is the only required key on each item.
input.photos[].photostringمطلوبA publicly accessible JPEG or PNG URL that Listings API fetches and stores. The field is named `photo`, not `url`.
input.photos[].typestringاختياريWhich slot the image fills: `LOGO`, `COVER`, or `ADDITIONAL`. Defaults to an additional photo.
input.photos[].starredbooleanاختياريStar the photo as it is attached, instead of a follow-up call to the star endpoint. Only additional photos can be starred, at most 4 per location.
input.photos[].sourcestringاختياريFree-text label recording where the image came from.

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

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

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photos": [      { "photo": "https://cdn.example.com/jenny-home/logo.png", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}

الاستجابات

200Photos attached inline. Returns the created photo records; `errors` is null on success and `request` is empty because nothing was queued.
Response
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {},      "photos": [        {          "id": "TWVkaWFGaWxlOjU4Nzg5MzE=",          "databaseId": 5878931,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png",          "thumbnailUrl": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.png",          "type": "LOGO",          "starred": false        },        {          "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": false        }      ],      "errors": null    }  }}
401Unauthenticated, missing or invalid API key.

يُرفق صورة واحدة أو أكثر بموقع. قدّم مصفوفة photos يحتوي كل عنصر فيها على الأقل على photo، وهو عنوان URL عام لصورة تجلبها Listings API وتخزّنها. يلزم دائمًا توفير locationId ومصفوفة photos غير فارغة.

شكلان للاستجابة الناجحة

تُرفع الدفعة الصغيرة مباشرةً ضمن الاستدعاء: يحتوي photos على الوسائط التي اكتمل رفعها، ويكون request كائنًا فارغًا، كما في المثال أعلاه. أما الدفعة الكبيرة فتُضاف إلى قائمة الانتظار، ويكون 200 نفسه على النحو التالي:

JSON
{  "data": {    "addLocationPhotos": {      "clientMutationId": null,      "success": true,      "request": {        "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",        "status": "PROCCESSING"      },      "photos": [],      "errors": null    }  }}

كلتا الحالتين ناجحتان، لذا تعامل معهما بالتحقق من وجود request.requestId بدلًا من افتراض أن photos يحتوي على بيانات.

حقل عنوان URL هو photo. وليس url ولا image. وإلى جانبه، يقبل كل عنصر الحقول الاختيارية type (LOGO أو COVER أو ADDITIONAL) وstarred وsource؛ ويُقبل أيضًا publisherOverride وpartnerMediaId لتكاملات الشركاء. لا تحتوي الصورة المُعادة على حقل caption.

حالة استخدام: إضافة الصور الأولية لموقع جديد. بعد إنشاء موقع مثل "Jenny Home" مباشرةً، استخدم POST لرفع شعاره وصور واجهته باستخدام عناوين URL في استدعاء واحد. تُعيد الاستجابة id لكل صورة جديدة، لتمرّره لاحقًا إلى نقطتي النهاية للتمييز بنجمة والإزالة.

حالة استخدام: إعادة استخدام صورة معتمدة في عدة مواقع. اجعل مواقع متعددة تشير إلى عنوان URL نفسه لصورة مستضافة في مصفوفات photos الخاصة بها، بحيث تستخدم جميع المواقع ملف المصدر نفسه.

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

  • يجب أن تكون الصور بتنسيق JPEG أو PNG. تُطبَّق قواعد منصة النشر المتعلقة بالحجم حسب الفئة (الحد الأدنى المعتاد نحو 10 KB، والحد الأقصى بضعة MB).
  • تُعالَج الدفعات الكبيرة بشكل غير متزامن. عندما يتجاوز حجم الدفعة حدًا محددًا على الخادم، يضيف الاستدعاء العمل إلى قائمة الانتظار بدلًا من الرفع المباشر ضمن الاستدعاء: يُعاد photos فارغًا وتُعيَّن قيمة request.requestId. استعلم دوريًا من GET /locations/photos/requests/{requestId} باستخدام ذلك المعرّف لتتبّع الاكتمال. تُحدَّد العتبة في إعدادات الخادم، لذا تعامل معها على أساس أن "الدفعات الكبيرة قد تُضاف إلى قائمة الانتظار" بدلًا من اعتماد رقم ثابت، وحدّد مسار التنفيذ بناءً على وجود request.requestId.
  • لا تحدّد مسار التنفيذ بناءً على request.status. في استجابة الإضافة إلى قائمة الانتظار، تكون قيمته السلسلة النصية الحرفية PROCCESSING، التي تختلف كتابتها عن PROCESSING التي تُبلغ عنها نقطة نهاية الاستعلام الدوري للمهمة نفسها. وجود request.requestId هو العلامة الموثوقة.
  • يؤدي تمرير starred: true بما يتجاوز الحد المسموح به البالغ 4 صور مميّزة بنجمة إلى فشل الاستدعاء بأكمله مع SY15012. يحتسب التحقق الصور المميّزة بنجمة الموجودة بالفعل في الموقع، إضافةً إلى العناصر المميّزة بنجمة في هذا الطلب.
  • يحتفظ الموقع بشعار واحد وصورة غلاف واحدة؛ وتؤدي إعادة رفع صورة من أيٍّ من هاتين الفئتين إلى استبدال الصورة الموجودة.
  • عيّن type صراحةً عندما تريد أن تكون الصورة شعارًا أو غلافًا. ومن دونه، تُخزَّن الصورة كصورة إضافية.
Request
curl -X POST 'https://listingsapi.com/api/v4/locations/photos' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "locationId": "TG9jYXRpb246MTgwMDI4OQ==",      "photos": [        {          "photo": "https://cdn.example.com/jenny-home/logo.png",          "type": "LOGO"        },        {          "photo": "https://cdn.example.com/jenny-home/storefront.jpg",          "type": "ADDITIONAL"        }      ]    }  }'
Run in playground