GET/api/v4/locations/photos/requests/{requestId}

查詢大量相片上傳狀態

傳回大量相片上傳請求目前的處理狀態。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

路徑

名稱類型必填說明
requestIdstring必填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.
Response
{  "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。

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \  -H "Authorization: API $LISTINGSAPI_KEY"