/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.
輪詢非同步大量相片上傳的狀態。當批次夠大時,新增地點相片會在背景處理該批次,並在 request 物件中傳回 requestId,而不是處理完成的媒體。觸發此行為的批次大小由伺服器端設定決定,並非公開的固定值,因此請檢查是否傳回 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 無法取得結果,因此請僅輪詢近期上傳呼叫所傳回的 ID。
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \ -H "Authorization: API $LISTINGSAPI_KEY"