일괄 요청
여러 Facebook 그래프 API 호출을 포함하는 하나의 HTTP 요청을 보냅니다. 종속적 작업은 순차적으로 처리되고 독립적 작업은 병렬로 처리됩니다. 모든 작업이 완료되면 통합된 응답이 반환되고 HTTP 연결이 닫힙니다.
응답 순서는 요청에서 작업 순서와 일치합니다. 그에 따라 응답을 처리하여 어떤 작업이 성공하였고, 이후의 작업에서 무엇을 가져와야 하는지 확인해야 합니다.
제한 사항
- 일괄 요청은 배치당 50개 요청으로 제한됩니다. 일괄 요청 내 각 호출은 API 호출 한도 및 리소스 한도를 계산하기 위해 별도로 계산됩니다. 예를 들어 10개의 API 호출이 포함된 일괄 요청은 호출 10개로 간주되며 일괄 요청 내 각 호출은 같은 방식으로 CPU 리소스 한도 계산에 포함됩니다. 자세한 내용은 사용 제한 가이드를 참조하세요.
일괄 요청
일괄 요청은 요청의 배열로 구성된 JSON 개체를 받습니다. 이 요청은 JSON 배열로 표현되는 논리적 HTTP 응답의 배열을 반환합니다. 각 응답에는 상태 코드, 선택적 헤더 배열 및 선택적 본문(JSON 인코딩된 문자열)이 포함됩니다.
일괄 요청을 보내려면 batch 매개변수가 JSON 개체인 엔드포인트로 POST 요청을 보내세요.
POST /ENDPOINT?batch=[JSON-OBJECT]
일괄 요청 샘플
이 예시에서는 앱이 관리하는 페이지 두 개에 대한 정보를 가져옵니다.
가독성을 높이기 위한 형식입니다.curl -i -X POST 'https://graph.facebook.com/me?batch=
[
{
"method":"GET",
"relative_url":"PAGE-A-ID"
},
{
"method":"GET",
"relative_url":"PAGE-B-ID"
}
]
&include_headers=false // Included to remove header information
&access_token=ACCESS-TOKEN'모든 작업이 완료되면 각 작업의 결과가 포함된 응답이 전송됩니다. 반환되는 헤더가 실제 API 응답보다 훨씬 더 큰 경우가 있기 때문에 효율성을 위해 헤더를 삭제해야 할 수도 있습니다. 헤더 정보를 포함하려면 include_headers 매개변수를 삭제하거나 true로 설정하세요.
응답 샘플
본문 필드에는 문자열 인코딩된 JSON 개체가 포함됩니다.
[
{
"code": 200,
"body": "{
\"name\": \"Page A Name\",
\"id\": \"PAGE-A-ID\"
}"
},
{
"code": 200,
"body": "{
\"name\": \"Page B Name\",
\"id\": \"PAGE-B-ID\"
}"
}
]복잡한 일괄 요청
일반적으로 서로 다른 HTTP 메서드를 사용하는 작업을 단일 일괄 요청으로 결합할 수 있습니다. GET과 DELETE 작업은 relative_url과 method 필드만 가질 수 있고 POST와 PUT 작업에는 선택적 body 필드가 포함될 수 있습니다. 본문은 URL 검색 문자열과 비슷한 원시 HTTP POST 문자열 형식으로 지정해야 합니다.
요청 샘플
다음 예시에서는 관리 대상이고 게시 권한이 있는 페이지에 새 게시물을 게시한 다음, 페이지의 피드를 한 번의 작업으로 가져옵니다.
curl "https://graph.facebook.com/PAGE-ID?batch=
[
{
"method":"POST",
"relative_url":"PAGE-ID/feed",
"body":"message=Test status update"
},
{
"method":"GET",
"relative_url":"PAGE-ID/feed"
}
]
&access_token=ACCESS-TOKEN"이 호출의 출력은 다음과 같습니다.
[
{ "code": 200,
"headers": [
{ "name":"Content-Type",
"value":"text/javascript; charset=UTF-8"}
],
"body":"{\"id\":\"…\"}"
},
{ "code": 200,
"headers": [
{ "name":"Content-Type",
"value":"text/javascript; charset=UTF-8"
},
{ "name":"ETag",
"value": "…"
}
],
"body": "{\"data\": [{…}]}
}
]다음 예시에서는 캠페인에 대해 새 광고를 만든 다음, 새로 만든 개체의 상세 정보를 가져옵니다. 본문 매개변수에 대한 URL 인코딩에 유의하세요.
curl \
-F 'access_token=...' \
-F 'batch=[
{
"method":"POST",
"name":"create-ad",
"relative_url":"11077200629332/ads",
"body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
},
{
"method":"GET",
"relative_url":"?ids={result=create-ad:$.data.*.id}"
}
]' \
https://graph.facebook.com다음의 예시에서는 여러 페이지를 비즈니스 관리자에 추가합니다.
curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
{
"method":"POST",
"name":"test1",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_1>"
},
{
"method":"POST",
"name":"test2",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_2>"
},
{
"method":"POST",
"name":"test3",
"relative_url":"<BUSINESS_ID>/owned_pages",
"body":"page_id=<PAGE_ID_3>"
},
]' \
"https://graph.facebook.com/v12.0"변수 설명:
<ACCESS_TOKEN>은business_management권한이 있는 액세스 토큰입니다.<BUSINESS_ID>는 페이지를 등록해야 하는 비즈니스 관리자의 ID입니다.<PAGE_ID_n>은 등록할 페이지의 ID입니다.
오류
요청된 작업 중 하나에서 오류가 발생할 수도 있습니다. 이는 (예를 들어) 개발자에게 요청된 작업을 수행할 수 있는 권한이 없기 때문입니다. 이 응답은 표준 그래프 API와 유사하지만 일괄 응답 구문으로 캡슐화됩니다.
[
{ "code": 403,
"headers": [
{"name":"WWW-Authenticate", "value":"OAuth…"},
{"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
"body": "{\"error\":{\"type\":\"OAuthException\", … }}"
}
]그래도 일괄 요청 내 다른 요청은 완료되며 200 상태 코드와 함께 정상적으로 반환됩니다.
시간 초과
크거나 복잡한 일괄 요청의 경우 일괄 요청 내 모든 작업을 완료하는 데 너무 오랜 시간이 소요되면 시간 초과가 발생할 수 있습니다. 이 경우 일괄 요청이 부분적으로 완료됩니다. 부분적으로 완료된 일괄 요청에서 성공적으로 완료된 요청은 200 상태 코드가 포함된 일반 출력을 반환합니다. 실패한 요청에 대한 응답은 null이 됩니다. 실패한 요청은 다시 시도할 수 있습니다.
JSONP를 사용한 일괄 호출
일괄 API는 나머지 그래프 API와 마찬가지로 JSONP를 지원합니다. JSONP 콜백 기능은 callback 검색 문자열 또는 양식 포스트(form post) 매개변수를 사용하여 지정됩니다.
여러 액세스 토큰 사용
단일 일괄 요청의 개별 요청은 자체 액세스 토큰을 쿼리 문자열 또는 양식 포스트(form post) 매개변수로 지정할 수 있습니다. 이 경우 최상위 수준 액세스 토큰은 폴백 토큰으로 간주되며 개별 요청에서 액세스 토큰이 명시적으로 지정되지 않은 경우에 사용됩니다.
이 기능은 여러 다른 사용자 또는 페이지 액세스 토큰을 사용하여 API를 쿼리하거나 일부 호출을 앱 액세스 토큰을 사용하여 해야 하는 경우에 유용합니다.
모든 개별 요청에 자체 토큰이 포함되어 있더라도 하나의 액세스 토큰을 최상위 수준 매개변수로 포함해야 합니다.
바이너리 데이터 업로드
일괄 호출에서 여러 바이너리 항목을 업로드할 수 있습니다. 이렇게 하기 위해서는 모든 바이너리 항목을 multipart/mime 첨부 파일로 요청에 추가해야 하며 각 작업에서 attached_files 속성을 사용하여 바이너리 항목을 참조해야 합니다. attached_files 속성은 쉼표로 구분된 첨부 파일 이름의 리스트를 값으로 취할 수 있습니다.
다음 예시에서는 단일 일괄 호출로 2장의 사진을 업로드하는 방법을 보여줍니다.
curl
-F 'access_token=…' \
-F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
-F 'file1=@cat.gif' \
-F 'file2=@dog.jpg' \
https://graph.facebook.com