그래프 API

재개 가능 업로드 API

재개 가능한 업로드 API를 사용하면 처음부터 다시 시작할 필요 없이 그래프 API에 대용량 파일을 업로드하고 중단된 업로드 세션을 다시 시작할 수 있습니다. 업로드가 끝나면 지원되는 다른 그래프 API 엔드포인트와 함께 업로드된 파일의 핸들을 사용할 수 있습니다.

재개 가능한 업로드 API 외에도 파일을 업로드할 수 있는 방법이 있습니다. 업로드를 지원하는 에지가 있는 노드는 많지만, 대부분이 대용량 파일을 처리하거나 중단된 업로드 세션을 다시 시작하는 수단을 제공하지 않습니다.

업로드된 파일 핸들을 지원하는 엔드포인트에 대한 참고 자료에는 해당 엔드포인트가 재개 가능한 업로드 API에서 반환한 핸들을 지원하는지 여부가 나와 있습니다.

업로드 단계

파일을 업로드하는 단계는 크게 두 개로 나뉩니다.

  1. 앱 업로드 엔드포인트를 사용하여 파일을 설명하고 업로드 세션을 만듭니다.
  2. 반환된 업로드 세션 ID를 사용하여 업로드 프로세스를 시작합니다.

업로드 프로세스가 성공할 경우 파일 핸들이 반환되고, 재개 가능한 업로드 API에서 반환한 파일 핸들을 지원하는 다른 엔드포인트와 함께 이를 사용할 수 있습니다.

1단계: 세션 만들기

파일을 설명하는 POST 요청을 앱 업로드 엔드포인트({app-id}/uploads)에 보냅니다. 요청에 성공하면 업로드 세션 ID가 반환되고 다음 단계에서 업로드를 시작하는 데 이를 사용할 수 있습니다.

요청 구문

POST https://graph.facebook.com/{api-version}/{app-id}/uploads
  &file_length={file-length}
  &file_type={file-type}
  &access_token={access-token}

매개변수 자리 표시자

  • {api-version} — 그래프 API 버전.
  • {app-id} — 앱 ID. 이 앱과 연결될 업로드된 파일입니다. 앱 사용자는 이 앱에서 관리자 또는 개발자 역할을 맡고 있어야 합니다.
  • file-length — 파일 크기(단위: 바이트).
  • file-type — 파일의 MIME 유형. 유효한 값: application/pdf, image/jpeg, image/jpg, image/png 및 video/mp4
  • {access-token} — 앱 사용자의 사용자 액세스 토큰.

사용 가능한 쿼리 매개변수와 지원되는 파일 유형의 전체 리스트는 앱 업로드 엔드포인트 참고 자료를 참조하세요.

응답

{
  "id": "{id}"
}

응답 속성 값:

  • {id} — 업로드 세션 ID.

요청 샘플

curl -X POST \
 "https://graph.facebook.com/v19.0/584544743160774/uploads?file_length=109981&file_type=image/png&access_token=EAAIT..."

응답 샘플 

{
    "id": "upload:MTphd..."
}

2단계: 업로드 시작

그래프 API 호스트 주소로 POST 요청을 보내서 업로드 세션을 시작하고 아래에 나와 있는 필수적인 헤더와 함께 업로드 세션 {id}를 첨부합니다. 요청이 성공하면 파일 핸들 {h}가 반환됩니다. 이는 재개 가능한 업로드 API에서 반환한 파일 핸들을 지원하는 그래프 API 엔드포인트와 함께 사용할 수 있습니다.

업로드 세션이 예상보다 오래 걸리거나 중단된 경우 중단 섹션에 나와 있는 단계를 따르세요.

요청 구문

POST https://graph.facebook.com/{api-version}/{upload-session-id}
  --header 'Authorization: OAuth {access-token}' 
  --header 'file_offset: 0'
  --data-binary @{file-name}

자리 표시자 값

  • {api-version} — 그래프 API 버전.
  • {upload-session-id} — 1단계에서 반환된 업로드 세션 ID.
  • {access-token} — 앱 사용자의 사용자 액세스 토큰. 앱 사용자는 1단계에서 타게팅된 앱에서 역할을 부여받아야 합니다.
  • {file-name} — 업로드할 파일 이름.

헤더에 액세스 토큰을 포함하지 않으면 요청이 실패합니다.

응답

{
  "h": "{h}"
}

응답 속성 값:

  • {h} — 업로드된 파일의 파일 핸들

요청 샘플

curl -X POST \
 "https://graph.facebook.com/v19.0/upload:MTphd..." \
 --header "Authorization: OAuth EAAIT..." \
 --header "file_offset: 0" \
 --data-binary @cats_are_jerks.png

응답 샘플 

{
    "h": "2:c2FtcGxl..."
}

중단

업로드 세션을 시작했지만 예상보다 오래 걸리거나 중단된 경우 그래프 API 호스트 주소로 GET 요청을 보내고 업로드 세션 ID를 첨부합니다. API가 중단 시점에서 업로드 프로세스를 다시 시작하는 데 사용할 수 있는 file_offset 값을 반환합니다.

요청 구문

GET https://graph.facebook.com/{api-version}/{upload-session-id}
  ?access_token={access-token}

자리 표시자 값:

  • {api-version} — 그래프 API 버전.
  • {upload-session-id} — 1단계: 세션 만들기에서 반환된 업로드 세션 ID.
  • {access-token} — 앱 사용자의 사용자 액세스 토큰.

응답

{
  "id": "{id}",
  "file_offset": {file-offset}
}

응답 속성 값:

  • {id} — 쿼리된 업로드 세션 ID.
  • {file-offset} — 성공적으로 업로드된 바이트 수를 나타내는 정수.

file_offset 값을 캡처하고 2단계: 업로드 시작을 반복하여 해당 file_offset 헤더에 값을 할당합니다. 그러면 중단 시점부터 업로드 프로세스가 다시 시작됩니다.

요청 샘플

curl -X GET \
 "https://graph.facebook.com/v19.0/upload:MTphd...&access_token=EAAIT..." \

응답 샘플 

{
  "id": "upload:MTphd",
  "file_offset": 5238
}