/api/v4/locations/photos/requests/{requestId}التحقق من حالة رفع الصور دفعة واحدة
يعيد حالة المعالجة الحالية لطلب رفع الصور دفعة واحدة.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| requestId | string | مطلوب | UUID request ID returned in the `request` object by the add-photos endpoint when it queues a batch instead of uploading it inline. |
الاستجابات
200Current status of the bulk upload request, with per-photo results once available.
{ "data": { "getLocationPhotosUploadStatus": { "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a", "status": "SUCCESS", "photos": [ { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null }, { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." } ] } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يستعلم دوريًا عن حالة عملية غير متزامنة لرفع الصور دفعة واحدة. عندما تكون الدفعة كبيرة بما يكفي، يعالجها إضافة صور الموقع في الخلفية ويعيد requestId في الكائن request بدلًا من الوسائط المكتملة. يُحدَّد حجم الدفعة الذي يؤدي إلى ذلك في إعدادات الخادم، وليس بقيمة ثابتة منشورة، لذا حدّد مسار المعالجة بالتحقق مما إذا كان request.requestId قد أُعيد، وليس بعدّ صورك. استعلم دوريًا من نقطة النهاية هذه باستخدام requestId حتى تصل المهمة إلى حالة نهائية.
حالة استخدام: تحديث شريط تقدّم الرفع. بعد رفع دفعة كبيرة، استعلم كل بضع ثوانٍ ما دامت قيمة status هي PROCESSING. بمجرد أن تتغير إلى SUCCESS أو ERROR، اقرأ المصفوفة photos لمعرفة نتيجة كل صورة: يحتوي كل عنصر على mediaId الناتج (عند النجاح)، بالإضافة إلى زوج status/errorMessage، لتتمكن من عرض الملفات التي رُفضت تحديدًا وأسباب رفضها (أبعاد غير صحيحة، أو تنسيق غير مدعوم، وما إلى ذلك)، بدلًا من اعتبار الدفعة بأكملها فاشلة.
قيم الحالة: PROCESSING (المعالجة لا تزال جارية: استعلم مجددًا)، SUCCESS (انتهت معالجة المهمة)، ERROR (فشلت المهمة نفسها؛ افحص photos[].errorMessage).
تشير قيمة status للمهمة إلى انتهاء المعالجة فقط، ولا تعني نجاح كل صورة. قد تظل المهمة ذات القيمة SUCCESS تحتوي على صور مرفوضة، كما في المثال أعلاه. بمجرد أن تغادر المهمة حالة PROCESSING، مرّ على عناصر photos[] واقرأ status وerrorMessage الخاصين بكل عنصر لمعرفة الصور التي رُفعت بنجاح.
تنبيه بشأن الاستعلام الدوري: اترك فاصلًا بين الاستعلامات: فتكرار استدعاء نقطة النهاية هذه في حلقة سريعة يؤدي سريعًا إلى مواجهة 429. التزم بالترويسة Retry-After، ويُفضَّل استخدام فاصل زمني قدره بضع ثوانٍ. لن يُفضي الاستعلام باستخدام requestId غير معروف أو منتهي الصلاحية إلى نتيجة، لذا استعلم فقط باستخدام المعرّفات التي أعادها استدعاء رفع حديث.
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \ -H "Authorization: API $LISTINGSAPI_KEY"