사업장에 사진 업로드

사업장에 이미지를 1개 이상 첨부합니다. photos 배열을 제공하며, 각 항목에는 최소한 photo(Listings API가 가져와 저장하는 공개 이미지 URL)가 있어야 합니다. locationId와 비어 있지 않은 photos 배열은 항상 필수입니다.

2가지 성공 응답 형태

소규모 배치는 즉시 업로드됩니다. 위 예시처럼 photos에는 처리가 완료된 미디어가 담기고 request는 빈 객체입니다. 대규모 배치는 대신 대기열에 추가되며, 동일한 200은 다음과 같은 형태입니다.

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

둘 다 성공 응답이므로, photos에 값이 있다고 가정하지 말고 request.requestId가 있는지 확인하여 처리합니다.

URL 필드는 photo입니다. url도 image도 아닙니다. 각 항목에는 이 필드와 함께 선택 사항인 type(LOGO, COVER 또는 ADDITIONAL), starred, source를 지정할 수 있으며, 파트너 통합을 위한 publisherOverride와 partnerMediaId도 허용됩니다. 반환된 사진에는 caption 필드가 없습니다.

사용 사례: 새 사업장의 초기 이미지 등록. "Jenny Home"과 같은 사업장을 생성한 직후, 한 번의 호출로 로고와 매장 외관 사진을 URL을 통해 POST로 업로드합니다. 응답은 새 사진 각각의 id를 반환하며, 이 값은 나중에 별표 지정 및 삭제 엔드포인트에 전달합니다.

사용 사례: 승인된 자산을 여러 사업장에서 재사용. 여러 사업장의 photos 배열에서 동일한 호스팅 이미지 URL을 참조하도록 지정하여 모든 사업장이 같은 원본 자산을 공유하게 합니다.

주의 사항.

• 이미지는 JPEG 또는 PNG여야 합니다. 게시 플랫폼의 크기 규칙은 카테고리별로 적용됩니다(일반적으로 최소 약 10 KB, 최대 수 MB입니다).
• 대규모 배치는 비동기적으로 처리됩니다. 서버 측 배치 크기 기준을 초과하면 호출은 즉시 업로드하는 대신 작업을 대기열에 추가하며, photos는 비어 있는 상태로 반환되고 request.requestId가 설정됩니다. 해당 id로 GET /locations/photos/requests/{requestId}를 폴링하여 완료 여부를 추적합니다. 임계값은 서버 측 설정이므로 고정된 숫자로 간주하지 말고 "대규모 배치는 대기열에 추가될 수 있음"으로 이해하고, request.requestId의 존재 여부에 따라 분기합니다.
• request.status의 값에 따라 분기하지 마십시오. 대기열에 추가된 응답에서 이 값은 리터럴 문자열 PROCCESSING이며, 폴링 엔드포인트가 같은 작업에 대해 보고하는 PROCESSING과 표기가 다릅니다. request.requestId의 존재 여부가 신뢰할 수 있는 신호입니다.
• 별표 지정이 허용되는 사진 수인 4개를 초과하도록 starred: true를 전달하면 전체 호출이 SY15012로 실패합니다. 이 검사는 사업장의 기존 별표 지정 사진 수와 이번 요청의 별표 지정 항목 수를 합산합니다.
• 사업장에는 로고 1개와 커버 1개만 유지되며, 어느 카테고리든 다시 업로드하면 기존 이미지가 교체됩니다.
• 이미지를 로고나 커버로 사용하려면 type을 명시적으로 설정합니다. 이 값이 없으면 이미지는 추가 사진으로 저장됩니다.