미디어 업로드

미디어 항목을 업로드하는 방법은 다음과 같이 두 단계로 진행됩니다.

1. 업로드 엔드포인트를 사용하여 미디어 파일의 바이트를 Google 서버에 업로드합니다. 그러면 업로드된 바이트를 식별하는 업로드 토큰이 반환됩니다.
2. 업로드 토큰과 함께 batchCreate 호출을 사용하여 사용자의 Google 포토 계정에 미디어 항목을 만듭니다.

이 단계에서는 단일 미디어 항목을 업로드하는 프로세스를 간략하게 설명합니다. 여러 개의 미디어 항목을 업로드하는 경우(프로덕션 애플리케이션에서 가능성이 높음) 업로드 권장사항을 검토하여 업로드 효율성을 개선하세요.

시작하기 전에

필수 승인 범위

사용자의 라이브러리 또는 앨범에 미디어 항목을 업로드하려면 photoslibrary.appendonly 범위가 필요합니다. 범위에 관한 자세한 내용은 승인 범위를 참고하세요.

허용되는 파일 형식 및 크기

이 표에 나열된 파일 형식은 업로드할 수 있습니다.

1단계: 바이트 업로드

업로드 요청을 사용하여 Google에 바이트를 업로드합니다. 업로드 요청이 성공하면 원시 텍스트 문자열 형식의 업로드 토큰이 반환됩니다. 이러한 업로드 토큰을 사용하여 batchCreate 호출로 미디어 항목을 만듭니다.

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

media-binary-data

upload-token

이미지의 권장 파일 크기는 50MB 미만입니다. 50MB를 초과하는 파일은 성능 문제가 발생하기 쉽습니다.

Google 포토 라이브러리 API는 중단된 업로드 재개를 지원합니다. 재개 가능한 업로드를 사용하면 미디어 파일을 여러 섹션으로 분할하고 한 번에 하나의 섹션을 업로드할 수 있습니다.

2단계: 미디어 항목 만들기

미디어 파일의 바이트를 업로드한 후 업로드 토큰을 사용하여 Google 포토에서 미디어 항목으로 만들 수 있습니다. 업로드 토큰은 생성된 후 1일 동안 유효합니다. 미디어 항목은 항상 사용자의 라이브러리에 추가됩니다. 미디어 항목은 앱에서 만든 앨범에만 추가할 수 있습니다. 자세한 내용은 승인 범위를 참고하세요.

새 미디어 항목을 만들려면 newMediaItems 목록을 지정하여 mediaItems.batchCreate를 호출합니다. 각 newMediaItem에는 simpleMediaItem 내에 지정된 업로드 토큰과 사용자에게 표시되는 설명(선택사항)이 포함됩니다.

설명 입력란은 1,000자(영문 기준)로 제한되며 사용자가 만든 의미 있는 텍스트만 포함해야 합니다. 예: '공원 여행' 또는 '휴일 저녁 식사' 파일 이름, 프로그래매틱 태그 또는 기타 자동 생성 텍스트와 같은 메타데이터는 포함하지 마세요.

최상의 성능을 위해 한 번의 호출에 여러 미디어 항목을 포함하여 mediaItems.batchCreate 호출 수를 줄입니다. 동일한 사용자에 대해 후속 호출을 실행하기 전에 항상 이전 요청이 완료될 때까지 기다립니다.

설명과 해당 업로드 토큰을 지정하여 사용자 라이브러리에 단일 미디어 항목 또는 여러 미디어 항목을 만들 수 있습니다.

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

albumId 및 albumPosition를 지정하여 앨범의 특정 위치에 미디어 항목을 삽입할 수도 있습니다.

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

앨범에서의 순서에 관한 자세한 내용은 보강 자료 추가를 참고하세요.

항목 생성 응답

mediaItems.batchCreate 호출은 만들려고 시도한 각 미디어 항목의 결과를 반환합니다. newMediaItemResults 목록은 상태를 나타내며 요청의 uploadToken를 포함합니다. 0이 아닌 상태 코드는 오류를 나타냅니다.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

항목이 추가되면 mediaItemId, productUrl, mediaMetadata가 포함된 mediaItem가 반환됩니다. 자세한 내용은 미디어 항목 액세스를 참고하세요.

미디어 항목이 동영상인 경우 먼저 처리해야 합니다. mediaItem에는 동영상 파일의 처리 상태를 설명하는 mediaMetadata 내에 status가 포함되어 있습니다. 새로 업로드된 파일은 사용하기 위해 READY되기 전에 먼저 PROCESSING 상태를 반환합니다. 자세한 내용은 미디어 항목 액세스를 참고하세요.

이 호출 중에 오류가 발생하면 권장사항에 따라 요청을 다시 시도하세요. 다음 요청 중에 이미지가 올바른 위치의 올바른 위치에 삽입될 수 있도록 성공적으로 추가된 항목을 추적하는 것이 좋습니다. 자세한 내용은 앨범 만들기를 참고하세요.

결과는 항상 업로드 토큰이 제출된 순서대로 반환됩니다.

업로드 권장사항

다음 권장사항 및 리소스를 따르면 업로드의 전반적인 효율성을 개선할 수 있습니다.

• 다음 사항에 유의하여 재시도 및 오류 처리 권장사항을 따르세요.
  • 429 오류는 할당량이 소진되었거나 너무 빠르게 너무 많은 호출을 실행하여 비율 제한이 적용된 경우 발생할 수 있습니다. 이전 요청이 완료될 때까지 동일한 사용자에 대해 batchCreate를 호출하지 마세요.
  • 429 오류는 재시도하기 전에 최소 30s 지연이 필요합니다. 요청을 재시도할 때 지수 백오프 전략을 사용합니다.
  • 500 오류는 서버에 오류가 발생할 때 발생합니다. 업로드 시에는 동일한 사용자에 대해 여러 쓰기 호출(예: batchCreate)을 동시에 실행하기 때문에 이러한 문제가 발생할 가능성이 큽니다. 요청의 세부정보를 확인하고 batchCreate를 동시에 호출하지 마세요.
• 재개 가능한 업로드 흐름을 사용하여 네트워크가 중단된 경우 업로드를 더 안정적으로 만들어 부분적으로 완료된 업로드를 재개할 수 있도록 허용하여 대역폭 사용량을 줄입니다. 이는 클라이언트 휴대기기에서 업로드하거나 대용량 파일을 업로드할 때 중요합니다.

또한 업로드 프로세스의 각 단계인 바이트 업로드와 미디어 항목 생성에 관한 다음 도움말을 참고하세요.

바이트 업로드

• 업로드 토큰을 검색하기 위한 바이트 업로드는 동시에 실행할 수 있습니다.
• 항상 각 업로드 호출의 X-Goog-Upload-Content-Type 헤더에 올바른 MIME 유형을 설정합니다.

미디어 항목 만들기

• 단일 사용자에 대해 batchCreate와 동시에 호출하면 안 됩니다.

  • 각 사용자에 대해 batchCreate를 차례로 호출합니다(직렬로).
  • 여러 사용자의 경우 항상 각 사용자에 대해 batchCreate를 차례로 호출합니다. 다른 사용자의 호출만 동시에 실행합니다.

• 총 호출 수를 최소화하려면 각 batchCreate 호출에 최대한 많은 NewMediaItems를 포함합니다. 최대 50개의 항목을 포함할 수 있습니다.

• 사용자가 작성한 의미 있는 설명 텍스트를 설정합니다. 파일 이름, 프로그래매틱 태그 또는 기타 자동 생성 텍스트와 같은 메타데이터는 설명 입력란에 포함하지 마세요.

둘러보기 예시

이 예에서는 가상 코드를 사용하여 여러 사용자의 미디어 항목 업로드를 안내합니다. 이 가이드의 목표는 업로드 프로세스의 두 단계(원시 바이트 업로드 및 미디어 항목 만들기)를 간략히 설명하고 효율적이고 탄력적인 업로드 통합을 빌드하기 위한 권장사항을 자세히 설명하는 것입니다.

1단계: 원시 바이트 업로드

먼저 모든 사용자의 미디어 항목에 대한 원시 바이트를 업로드할 대기열을 만듭니다. 사용자별로 반환된 각 uploadToken를 추적합니다. 다음 핵심 사항을 기억하세요.

• 동시 업로드 스레드 수는 운영 환경에 따라 다릅니다.
• 필요에 따라 업로드 대기열의 순서를 변경해 보세요. 예를 들어 사용자당 남은 업로드 수, 사용자의 전반적인 진행 상황 또는 기타 요구사항에 따라 업로드의 우선순위를 지정할 수 있습니다.

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

2단계: 미디어 항목 만들기

1단계에서는 여러 사용자의 여러 바이트를 동시에 업로드할 수 있지만 2단계에서는 한 번에 각 사용자를 한 번만 호출할 수 있습니다.

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

모든 업로드 및 미디어 생성 호출이 완료될 때까지 이 프로세스를 계속합니다.