Meta의 Facebook 스토리 API

이 문서에서는 Facebook 스토리 API를 사용하여 Facebook 페이지에 스토리를 게시하는 방법을 보여줍니다.

스토리를 게시하려면 앱에서 다음 단계를 수행하세요.

1. Meta 서버에 앱 사용자의 미디어 업로드
2. 앱 사용자의 페이지에 미디어를 스토리로 게시

시작하기 전에

이 가이드에서는 페이지 API 개요를 읽었고 필요한 구성 요소를 구현했으며 시작하기 가이드를 성공적으로 완료한 것으로 가정합니다.

• Facebook 로그인이나 비즈니스용 Facebook 로그인을 구현하여 Facebook 페이지에 액세스하고 페이지 액세스 토큰을 수신하는 데 필요한 권한을 앱 사용자에게 요청해야 합니다.
• 앱 사용자는 페이지 액세스 토큰에 나와 있는 페이지에서 CREATE_CONTENT 작업을 수행하고 앱에 다음 권한을 부여해야 합니다.

  • pages_manage_posts
  • pages_read_engagement
  • pages_show_list

API 요청에서 비즈니스 시스템 사용자를 사용하는 경우 business_management 권한도 필요합니다.

미디어 요구 사항

다음 사양에 맞는 사진이나 동영상을 제공해야 합니다.

사진 사양

동영상 사양

제한 사항

• 스토리용으로 업로드한 사진이나 동영상은 이전에 게시된 게시물에 사용하지 않은 것이어야 합니다.
• 동영상 스토리는 60초를 초과할 수 없습니다.
• 스토리 리스트를 보기 위해 GET 요청에 보관된 스토리를 포함하려면 Facebook 스토리 보관을 활성화해야 합니다.

모범 사례

이 문서 내의 코드 예시는 가독성을 높이기 위해 형식을 지정했습니다. 굵은 기울임꼴 값(예: page_id)을 자신의 값으로 바꾸세요.

동영상 스토리

Facebook 페이지에 동영상 스토리를 게시하려면, Meta 서버로 동영상 업로드 세션을 초기화하고 Meta 서버에 동영상을 업로드한 다음 동영상 스토리를 게시합니다.

1단계: 세션 초기화

업로드 세션을 초기화하려면 /page_id/video_stories 엔드포인트로 POST 요청을 보냅니다. 이때 page_id는 Facebook 페이지의 ID이며 upload_phase 매개변수는 start로 설정합니다.

요청 예시

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

요청에 성공하면 앱이 동영상 ID와 동영상을 업로드할 Facebook URL을 포함한 JSON 응답을 받게 됩니다.

응답 예시

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v25.0/video_id",
}  

2단계: 동영상 업로드

업로드 세션을 초기화하고 업로드 URL을 받았으므로 이제 동영상을 업로드할 수 있습니다. 다음 중 한 가지를 업로드할 수 있습니다.

• 공개 http/https 서버(예: CDN)에서 호스팅되는 동영상 파일
• 기기의 로컬 동영상 파일

호스팅된 파일 업로드

호스팅된 파일을 업로드하려면 다음 매개변수를 포함하여 초기화 단계에서 받은 upload_url 엔드포인트로 POST 요청을 보냅니다.

• 동영상 파일의 URL로 설정된 file_url

호스트가 rupload.facebook.com이어야 합니다.

이제 API는 robots.txt을 통해 액세스를 제한하는 사이트에서 호스팅되는 파일을 거부합니다. 개발자는 호스팅 사이트에서 'facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)' 사용자 에이전트가 호스팅된 파일을 가져올 수 있도록 해야 합니다.

Meta CDN(예: fbcdn URLs)에서 호스팅되는 파일은 거부됩니다. 대신 개발자는 각 페이지에 동영상을 업로드하지 않고 교차 게시 기능을 사용하여 여러 페이지에 동영상을 게시합니다. 교차 게시에 대한 내용은 상세 지침을 참조하세요.

요청 예시

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

로컬 파일 업로드

로컬 파일을 업로드하려면 다음 매개변수를 포함하여 초기화 단계에서 받은 upload_url 엔드포인트로 POST 요청을 보냅니다.

• 0으로 설정된 offset
• 업로드되는 동영상의 총 용량(바이트)으로 설정된 file_size

요청 예시

curl -X POST "https://rupload.facebook.com/video-upload/v25.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

업로드에 성공하면 앱은 success가 true로 설정된 JSON 응답을 받게 됩니다.

업로드 응답 예시

{
    "success": true
}  

중단된 업로드

동영상 업로드가 중단된 경우 업로드를 다시 시작하거나 끊어진 부분부터 재개할 수 있습니다.

• 업로드를 다시 시작하려면 POST 요청을 다시 보내고 offset을 0으로 설정하세요.
• 업로드를 끊어진 부분부터 재개하려면 POST 요청을 다시 보내고 offset을 상태 확인을 통해 얻은 bytes_transfered 값으로 설정하세요.

업로드 상태 가져오기

업로드나 게시 중에 동영상 상태를 확인하려면 다음 매개변수를 포함하여 /video_id 엔드포인트로 GET 요청을 보내세요.

• status로 설정된 fields

요청 예시

curl -X GET "https://graph.facebook.com/v25.0/video_id" \
	-d "fields=status"

요청에 성공하면 앱은 다음을 포함한 JSON 응답을 받게 됩니다.

• 다음을 포함한 status 개체:

  • ready, processing, expired 또는 error 값으로 설정된 video_status
  • 다음 키-값 쌍을 포함한 uploading_phase 개체:

    • in_progress, not_started, complete 또는 error로 설정된 status
    • 업로드된 용량(바이트)으로 설정된 bytes_transfered. 업로드가 중단된 경우 offset의 값으로 사용할 수 있습니다.
  • 다음 키-값 쌍을 포함한 processing_phase 개체:

    • in_progress, not_started, complete 또는 error로 설정된 status
  • 다음 키-값 쌍을 포함한 processing_phase 개체:

    • in_progress, not_started, complete 또는 error로 설정된 status
    • published 또는 not_published로 설정된 publish_status
    • 실제 또는 게시된 시간의 UNIX 타임스탬프로 설정된 publish_time

응답 예시

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

3단계. 동영상 스토리 게시

동영상 스토리를 페이지에 게시하려면 다음 매개변수를 포함하여 /page_id/video_stories 엔드포인트로 POST 요청을 보냅니다.

• 업로드한 동영상의 ID로 설정된 video_id
• finish로 설정된 upload_phase

요청 예시

curl -X POST "https://graph.facebook.com/v25.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

요청에 성공하면 앱이 다음 키-값 쌍을 포함하는 JSON 응답을 받게 됩니다.

• true로 설정된 success
• 스토리 게시물의 ID로 설정된 post_id

응답 예시

{
  "success": true,
  "post_id": 1234
}

사진 스토리

1단계. 사진 업로드

/page_id/photos 엔드포인트를 사용하여 Meta 서버로 사진을 업로드하는 방법을 알아보려면 페이지 게시물 참고 자료 를 참조하세요. published 매개변수를 포함하고 이를 false로 설정합니다.

2단계. 사진 스토리 게시

사진 스토리를 페이지로 게시하려면 다음 매개변수를 포함하여 /page_id/photo_stories 엔드포인트로 POST를 보냅니다.

• 업로드한 사진의 ID로 설정된 photo_id

요청 예시

curl -X POST "https://graph.facebook.com/v25.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

요청에 성공하면 앱이 다음 키-값 쌍을 포함하는 JSON 응답을 받게 됩니다.

• true로 설정된 success
• 스토리 게시물의 ID로 설정된 post_id

응답 예시

{
  "success": true,
  "post_id": 1234
}

스토리 가져오기

페이지에 대한 모든 스토리와 각 스토리에 대한 데이터의 리스트를 가져오려면 /page_id/stories 엔드포인트로 GET 요청을 보내세요. 이때 page_id는 조회하려는 페이지의 ID입니다.

요청 예시

    
curl -i -X GET "https://graph.facebook.com/v25.0/page_id/stories"

요청에 성공하면 앱이 개체의 배열을 포함하는 JSON 응답을 받게 됩니다. 이때 각 개체에는 페이지에 게시된 스토리에 대한 정보가 포함됩니다. 각 개체에는 다음 키-값 쌍이 포함됩니다.

• 게시된 스토리 게시물의 ID로 설정된 post_id
• PUBLISHED, ARCHIVED로 설정된 status
• 스토리가 게시된 시점의 UNIX 타임스탬프로 설정된 creation_time
• video 또는 photo로 설정된 media_type
• 스토리 게시물의 동영상 또는 사진의 ID로 설정된 media_id
• 스토리 게시물의 Facebook URL로 설정된 url(예: https://facebook.com/stories/8283482737484972)

응답 예시

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

since 및 until 매개변수를 사용하여 상태, 게시/보관, 날짜 기준으로 스토리를 필터링할 수 있습니다.

기타 참고 자료

이 가이드에서 언급된 엔드포인트와 개념에 대해 자세히 알아보세요.

관련 가이드

• 비즈니스 시스템 사용자
• Facebook 로그인
• 비즈니스용 Facebook 로그인
• 그래프 API – since와 until을 사용한 페이지 매김된 결과

엔드포인트 참고 자료

• 페이지 참고 자료
• 페이지 동영상 스토리 참고 자료
• 페이지 사진 스토리 참고 자료
• 동영상 참고 자료
• 스토리 인사이트 참고 자료