คำขอแบบแบตช์

ส่งคำขอ HTTP รายการเดียวที่มีการเรียกใช้ API กราฟของ Facebook หลายรายการ ระบบจะประมวลผลแบบคู่ขนานสำหรับการดำเนินการที่ไม่ขึ้นต่อกัน และจะประมวลผลแบบเป็นลำดับสำหรับการดำเนินการที่ขึ้นต่อกัน เมื่อการดำเนินการทั้งหมดเสร็จสมบูรณ์ ระบบจะส่งการตอบกลับแบบรวมกลับมาให้คุณและการเชื่อมต่อ HTTP จะปิดลง

การเรียงลำดับของการตอบกลับจะสอดคล้องกับลำดับของการดำเนินการในคำขอ คุณควรประมวลผลคำขอตามลำดับ เพื่อดูว่าการดำเนินการใดสำเร็จและการดำเนินการใดต้องทำอีกครั้งในภายหลัง

ข้อจำกัด

• คำขอแบบแบตช์จำกัดอยู่ที่ 50 คำขอต่อแบตช์ การเรียกใช้แต่ละรายการในแบตช์จะนับเป็นรายการแยกกัน เพื่อวัตถุประสงค์ในการคำนวณขีดจำกัดการเรียกใช้ API และขีดจำกัดทรัพยากร ตัวอย่างเช่น แบตช์ที่มีการเรียกใช้ API 10 ครั้ง จะถูกนับเป็นการเรียก 10 ครั้ง และการเรียกแต่ละครั้งในแบตช์นั้นจะนับรวมในขีดจำกัดทรัพยากร CPU ในลักษณะเดียวกันด้วย โปรดดูข้อมูลเพิ่มเติมจากคำแนะนำเกี่ยวกับการจำกัดอัตราของเรา
• คำขอแบบแบตช์ไม่สามารถรวมชุดโฆษณาหลายรายการภายใต้แคมเปญเดียวกันได้ เรียนรู้เพิ่มเติมเกี่ยวกับการส่งคำขอ API การตลาดเป็นแบตช์

คำขอแบบแบตช์

คำขอแบบแบตช์ต้องใช้อ็อบเจ็กต์ JSON ที่ประกอบด้วยอาร์เรย์ของคำขอของคุณ โดยจะส่งกลับอาร์เรย์ของการตอบกลับโดย HTTP เชิงตรรกะที่แสดงในรูปแบบอาร์เรย์ JSON แต่ละการตอบกลับมีโค้ดสถานะ อาร์เรย์ส่วนหัวที่ระบุหรือไม่ก็ได้ และส่วนเนื้อความที่ระบุหรือไม่ก็ได้ (ซึ่งเป็นสตริงที่เข้ารหัสแบบ JSON)

หากต้องการส่งคำขอเป็นแบตช์ ให้ส่งคำขอ POST ไปยังปลายทางที่พารามิเตอร์ batch เป็นอ็อบเจ็กต์ JSON ของคุณ

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 ที่จะระบุหรือไม่ก็ได้ ควรจัดรูปแบบส่วนเนื้อความเป็นสตริงดิบแบบ HTTP POST เหมือนกับสตริงสืบค้นข้อมูลแบบ URL

ตัวอย่างคำขอ

ตัวอย่างต่อไปนี้เป็นการเผยแพร่โพสต์ไปยังเพจที่เราจัดการและมีสิทธิ์ในการเผยแพร่ และจากนั้นเผยแพร่ไปยังฟีดของเพจในการดำเนินการเดียว

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\": [{…}]}
    }
]

ตัวอย่างต่อไปนี้สร้างโฆษณาใหม่สำหรับแคมเปญหนึ่ง จากนั้นจะได้รับรายละเอียดเกี่ยวกับอ็อบเจ็กต์ที่สร้างขึ้นใหม่ โปรดสังเกต URLEncoding สำหรับพารามิเตอร์ของเนื้อความ

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 แบบเป็นแบตช์รองรับ JSONP เหมือนกับส่วนที่เหลือของ API กราฟ - ฟังก์ชันการการเรียกกลับของ JSONP นั้นกำหนดโดยการใช้สตริงสืบค้นข้อมูล callback หรือพารามิเตอร์โพสต์แบบฟอร์ม

การใช้โทเค็นการเข้าถึงหลายรายการ

คำขอแต่ละรายการในแบตช์สามารถระบุโทเค็นการเข้าถึงของตัวเองได้ทั้งในแบบสตริงการสืบค้นหรือพารามิเตอร์โพสต์แบบฟอร์ม ในกรณีนั้น โทเค็นการเข้าถึงระดับบนสุดจะถือเป็นโทเค็นสำรองและจะถูกใช้หากคำขอนั้นไม่ได้ระบุโทเค็นการเข้าถึงไว้อย่างชัดเจน

วิธีนี้อาจมีประโยชน์เมื่อคุณต้องการสืบค้น API โดยใช้โทเค็นการเข้าถึงของผู้ใช้หรือเพจหลายรายการ หรือถ้าต้องการสร้างการเรียกใช้บางส่วนโดยใช้โทเค็นการเข้าถึงแอพ

คุณจำเป็นต้องรวมโทเค็นการเข้าถึงในพารามิเตอร์ระดับบนสุดถึงแม้แต่ละคำขอจะมีโทเค็นเป็นของตัวเองแล้ว

การอัพโหลดข้อมูลไบนารี

คุณสามารถอัพโหลดข้อมูลไบนารีหลายรายการในการเรียกใช้แบตช์เดียวได้ โดยคุณจำเป็นต้องเพิ่มรายการไบนารีทั้งหมดเป็นไฟล์แนบแบบหลายส่วน/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