비동기식 요청과 일괄 요청

비동기식 요청을 사용하여 광고를 만들고 차단할 필요 없이 여러 광고 요청을 보냅니다. 요청이 완료된 후 호출할 URL을 지정하거나 요청 상태를 확인합니다. 광고, 참고 자료를 참조하세요.

광고를 관리하는 가장 효율적인 방법은 일괄 요청을 사용하는 것입니다. 더 일반적인 일부 요청을 보내려면 이를 사용하세요.

비동기식 요청

예를 들어 비동기식 요청 세트의 상태를 가져오는 방법은 다음과 같습니다.

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

이렇게 하면 비동기식 요청 세트의 전체 상태가 JSON 개체로 반환됩니다. 모든 필드가 기본적으로 표시되지는 않습니다. 쿼리에 기본이 아닌 필드를 포함하려면 fields에 해당 필드를 지정하세요(예: fields=id,owner_id,name,total_count,success_count,error_count,is_completed).

비동기식 요청 세트의 전체 상태를 가져오고 나면 각 요청의 상세 정보를 가져올 수 있습니다.

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

이렇게 하면 비동기식 요청 세트 내의 각 요청 상태와 상세 정보가 반환됩니다. 비동기식 광고를 만드는 경우 광고 하나를 만들려면 요청 하나를 보내세요. 상태 매개변수는 요청 자체의 상태를 기준으로 요청을 필터링하는 데 사용되며 다음 값을 조합할 수 있습니다.

• initial – 아직 처리되지 않음
• in_progress – 요청이 처리 중임
• success – 요청이 성공적으로 완료됨
• error – 요청이 완료되었으나 실패함
• canceled – 사용자가 요청을 취소함

응답은 기본 필드가 포함된 JSON 배열입니다. 기본 외의 필드를 포함하려면 fields에서 지정하세요(예: fields=id,scope_object_id,status,result,input,async_request_set).

요청 상세 정보 가져오기

특정 비동기식 요청의 상세 정보를 가져오려면 다음과 같이 호출합니다.

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests   

이렇게 하면 위에 나열된 필드를 포함한 JSON 개체가 반환됩니다.

광고의 요청 세트 리스트

여러 개의 비동기식 광고 요청 세트를 만들 수 있습니다. 광고 계정의 모든 비동기식 광고 요청 세트를 쿼리하는 방법은 다음과 같습니다.

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

이렇게 하면 비동기식 요청 세트 개체로 구성된 JSON 배열이 반환됩니다. 각 개체는 비동기식 요청 세트 섹션에 지정된 것과 같습니다. is_completed로 결과를 필터링할 수 있습니다. is_completed=true인 경우 완료된 비동기식 요청 세트만 표시됩니다.

광고 세트에 대한 요청 리스트

여러 광고 세트에서 광고를 만들기 위해 비동기식 호출을 보낼 수 있습니다. 각 광고 세트의 상태를 가져오려면 한 광고 세트의 모든 광고 만들기 요청을 가져오세요.

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_SET_ID>/asyncadrequests

이렇게 하면 비동기식 요청 개체로 구성된 JSON 배열이 반환됩니다. 상태, 필드 필터, 비동기식 요청 필드는 https://graph.facebook.com/<API_VERSION>/<REQUEST_SET_ID>/requests API와 같습니다.

요청 세트 업데이트

비동기식 요청 세트의 name, notification_uri 및 notification_mode를 변경할 수 있습니다.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

업데이트 성공 시 true가 반환됩니다. 알림이 전송되기 전에 notification_uri와 notification_mode만 변경할 수 있습니다.

요청 취소

비동기식 요청을 취소할 수는 있지만 요청이 아직 처리되지 않은 경우에만 가능합니다.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_ID>

취소 성공 시 true가 반환됩니다. 비동기식 요청 세트에서 처리되지 않은 요청을 취소할 수도 있습니다.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<REQUEST_SET_ID>

취소 성공 시 true가 반환됩니다.

비동기식 예시

특정 비동기식 요청의 상태를 가져오는 방법은 다음과 같습니다.

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/"

반환 값:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

요청 결과를 가져오는 방법은 다음과 같습니다.

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v21.0/requests"

반환 결과:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

광고 계정의 요청 세트 리스트를 가져오는 방법은 다음과 같습니다.

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_71597454/asyncadrequestsets"

반환 결과:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

캠페인의 요청 리스트를 가져오는 방법은 다음과 같습니다.

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v21.0/6008248529789/asyncadrequests"
    

반환 값:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

일괄 요청

일괄 요청을 사용하여 여러 개의 그래프 API 호출을 하나의 HTTP 요청으로 결합하세요. 마케팅 API는 이 요청을 구성하는 요청으로 분할합니다. 따라서 마케팅 API와 상호작용할 때는 일괄 요청이 가장 효율적입니다. 효율성을 훨씬 더 높이려면 별도의 처리 대화창을 사용하여 병렬 일괄 요청을 보낼 수 있습니다.

광고, 광고 크리에이티브 및 광고 세트에 대한 일괄 요청은 매우 유사하므로 여기에서는 따로 설명하지 않습니다. 자세한 내용은 그래프 API 일괄 요청과 ETag를 참조하세요.

광고 만들기

배치 요청에서 광고 크리에이티브와 기타 광고 개체를 제공할 수 있습니다. 예를 들어 광고 크리에이티브 하나와 서로 다른 타게팅 사양 세 개를 사용하여 광고 세 개를 만들 수 있습니다. 먼저 광고 크리에이티브를 정의한 다음 각 광고를 만들 때 참조하세요.

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

응답에는 각 요청의 개별 응답 코드와 표준 그래프 API 응답이 포함됩니다. 자세한 내용은 여러 개의 API 요청 보내기를 참조하세요.

배치 요청 과정에서는 JSONPath 표현식 형식을 사용하여 이전 요청을 참조합니다.

광고 업데이트

배치 요청으로 광고를 업데이트할 수 있습니다. 광고 세 개의 입찰가를 업데이트하는 방법은 다음과 같습니다.

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

상대적 URL에 redownload=1을 포함하면 광고 ID를 포함한 전체 광고 상세 정보를 가져올 수 있습니다. 이렇게 하면 업데이트한 광고를 식별하는 데 도움이 됩니다.

광고 크리에이티브를 업데이트하려면 전체 크리에이티브를 지정하거나 새로운 크리에이티브 ID를 제공하세요. 광고 크리에이티브를 만든 후에는 이름과 게재 상태를 제외하고 수정할 수 없기 때문입니다.

광고 읽기

광고가 많은 경우 배치 요청 내에서 여러 개의 요청으로 분할하세요.

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

6003356308839와 6004164369439는 광고 ID이고 6003356307839와 6004164259439는 광고 세트 ID입니다.

광고 인사이트

광고 인사이트가 많은 경우 배치 요청 내에서 여러 개의 요청으로 분할하세요.

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

이 예시에서 6003356308839와 6004164369439는 광고 ID이고 6003356307839와 6004164259439는 광고 세트 ID입니다.

광고가 많은 광고 계정의 경우 요청 시간을 초과할 수 있으므로 act_<account_ID>/adgroupstats 사용을 권장하지 않습니다.

도달 추산치의 배치 요청

한 건의 일괄 요청에서 도달 추산치를 최대 50개까지 요청할 수 있습니다. 다음 예시는 서로 다른 타게팅 사양 2가지에 대해 도달 추산치를 요청하는 방법을 보여줍니다.

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

배치 API

배치 API를 사용하면 요청을 배치로 묶어서 비동기식으로 전송할 수 있습니다. 여러 그래프 API 호출을 하나의 HTTP 요청으로 구분하고 차단할 필요 없이 비동기식으로 실행합니다. 관련 작업 간의 종속성을 지정할 수도 있습니다.

Facebook은 독립된 각 작업을 동시에 처리하며 종속된 작업은 순차적으로 처리합니다. 각 API 호출은 요청을 최대 1,000개까지 포함할 수 있습니다.

배치 API 호출

배치 API를 호출하는 방법은 다음과 같습니다.

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

HTTP POST 요청의 배열을 JSON 배열로 제공하세요. 각 요청에는 다음 항목이 포함됩니다.

• name
• relative_url - URL의 graph.facebook.com 이후 부분
• body

API에서 요청 진행 상태를 쿼리하는 데 사용할 ID가 반환됩니다.

예를 들어 이전 요청을 참조하려면 JSONPath 형식의 광고 세트를 사용하여 캠페인을 만드세요.

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

요청 세트 상태를 가져오는 방법은 다음과 같습니다.

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>"

이렇게 하면 비동기식 요청 세트의 전체 상태가 JSON 개체로 반환됩니다. 모든 필드가 기본적으로 반환되는 것은 아닙니다. 필드를 포함하려면 fields를 지정하세요(예: fields=id,owner_id,name,total_count,success_count,error_count,is_completed).

전체 상태를 가져오고 나면 각 요청의 상세 정보를 가져올 수 있습니다.

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v21.0/<REQUEST_SET_ID>/requests"

이렇게 하면 상세 정보가 JSON 배열로 반환됩니다. 기본 외의 필드를 포함하려면 fields에서 지정하세요(예: fields=id,scope_object_id,status,result,input,async_request_set).

광고 계정의 배치 API 요청 리스트

여러 배치 API 요청 세트를 만들 수 있습니다. 광고 계정에서 모든 요청 세트를 쿼리하는 방법은 다음과 같습니다.

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/async_requests"

ETags

마케팅 API는 Etags를 지원합니다. 이는 마지막 확인 이후에 쿼리 대상 데이터가 변경되었는지 확인하는 데 도움이 됩니다. 사용 방법은 다음과 같습니다.

1. 호출할 때 응답 헤더에는 API 호출에서 반환된 데이터의 해시 값이 있는 ETag가 포함됩니다. 이 ETag 값을 다음 단계에서 사용하기 위해 저장합니다.
2. 다음번에 동일한 API 호출을 보낼 때는 저장한 ETag 값과 함께 If-None-Match 요청 헤더를 포함합니다.
3. 데이터가 변경되지 않은 경우 응답 상태 코드는 304 – Not Modified이고 데이터가 반환되지 않습니다.
4. 마지막 쿼리 이후 데이터가 변경된 경우에는 데이터가 평소와 같이 새 ETag와 함께 반환됩니다. 새 ETag 값을 저장하고 이후 호출에 사용합니다.

ETag는 데이터 트래픽을 줄이는 데 도움이 되지만 If-None-Match GET은 여전히 앱 사용 제한에 반영됩니다.

ETag는 해당 형식을 포함한 API 호출의 전체 응답을 사용하여 계산됩니다. 응답 형식은 사용자 에이전트 문자열의 영향을 받을 수 있습니다. 따라서 동일한 클라이언트에서 보낸 호출은 사용자 에이전트가 같아야 합니다.

Etags 예시

사용자 광고 계정이 변경되었는지 확인하는 방법은 다음과 같습니다.

1단계: 현재 데이터의 ETag를 확인합니다.

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

응답은 다음과 같습니다.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

이 예시에서 ETag는 "7776cdb01f44354af8bfa4db0c56eebcb1378975"입니다. 참고로 ETag에는 큰따옴표(")가 포함됩니다.

2단계: 데이터가 변경되었는지 확인합니다.

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

데이터가 변경되지 않은 경우 응답은 다음과 같습니다.

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

304 Not Modified 응답에 유의하세요. 데이터가 변경된 경우 일반 API 응답이 반환됩니다.

사용자의 광고가 변경되었는지 확인하는 배치 예시입니다.

1단계: 현재 데이터의 ETag를 확인합니다.

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

응답에는 다음과 같이 ETag 값이 포함됩니다.

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

이 예시에서 ETag는 "21d371640127490b2ed0387e8af3f0f8c9eff012" 및 "410e53bb257f116e8716e4ebcc76df1c567b87f4"입니다. 참고로 ETag에는 큰따옴표(")가 포함됩니다.

2단계: 데이터가 변경되었는지 확인합니다.

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

데이터가 변경되지 않은 경우 응답은 다음과 같습니다.

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

304 Not Modified 응답에 유의하세요. 데이터가 변경된 경우 일반 API 응답이 반환됩니다.