การใช้ API กราฟ

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

ข้อมูลพื้นฐาน

เราได้อธิบายถึงข้อมูลพื้นฐานเกี่ยวกับศัพท์เฉพาะและโครงสร้างของ API กราฟไว้ในภาพรวม API กราฟ ส่วนต่อไปนี้จะอธิบายเพิ่มเติมเกี่ยวกับการดำเนินการต่างๆ ที่สามารถทำได้โดยใช้ API

การอ่าน

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

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

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

โหนด /me คือปลายทางพิเศษที่แปลเป็น user_id ของบุคคล (หรือ page_id ของเพจ Facebook) ซึ่งเป็นเจ้าของโทเค็นการเข้าถึงที่กำลังใช้เพื่อสร้างการเรียก API หากคุณมีโทเค็นการเข้าถึงสำหรับผู้ใช้ คุณควรเรียกคืนรูปภาพของผู้ใช้ทั้งหมดโดยใช้:

GET graph.facebook.com
  /me/photos

การตอบสนองที่คุณได้รับจะแตกต่างกันไปตามโหนดหรือจุดเชื่อมโยงที่คุณกำลังอ่าน แต่จะตอบสนองโดยใช้รูปแบบทั่วไปต่อไปนี้:

{
   "fieldname": {field-value},
   ....
}

การเลือกฟิลด์

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

ตัวอย่างเช่น การเรียก API กราฟต่อไปนี้โดยใช้โทเค็นการเข้าถึงผู้ใช้งานของคุณเอง https://graph.facebook.com/me?fields=id,name,picture จะส่งกลับเฉพาะ ID, ชื่อ และรูปภาพในโปรไฟล์ของคุณ:

GET graph.facebook.com/me?fields=id,name,picture

การเรียงลำดับ

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

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order ต้องเป็นหนึ่งในค่าต่อไปนี้:

  • chronological
  • reverse_chronological

การค้นหา URL

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

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

เรียนรู้เพิ่มเติมเกี่ยวกับการหาข้อมูลของลิงก์ที่ไปยังแอพด้วย API ดัชนีได้ในเอกสารประกอบของเราเกี่ยวกับลิงก์ที่ไปยังแอพ

การปรับเปลี่ยนคำขอ API

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

ชื่อ คำอธิบาย ประเภท

return_ssl_resources

สำหรับใช้เมื่อคุณต้องการให้ส่งกลับรูปภาพผ่านการเชื่อมต่อแบบปลอดภัย (HTTPS) เพื่อหลีกเลี่ยงคำเตือนเนื้อหาปนกันในเบราว์เซอร์

bool

locale

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

Locale

ตัวปรับเปลี่ยนอื่นสำหรับการแบ่งเป็นหน้าและการตรวจสอบภายในจะแสดงไว้ด้านล่างนี้

การสร้างคำขอซ้อนคำขอ

คุณสมบัติการขยายฟิลด์ของ API กราฟทำให้คุณสามารถซ้อนการสืบค้นกราฟหลายๆ ครั้งได้อย่างมีประสิทธิภาพในการเรียกครั้งเดียว ทรัพยากรบางชนิด รวมถึง API โฆษณาส่วนใหญ่ไม่สามารถที่จะใช้การขยายฟิลด์บนการเชื่อมโยงบางอย่างหรือทั้งหมดได้

ตัวอย่างเช่น คุณสามารถขอรูปภาพ N ภาพแรกของอัลบั้ม K แรกด้วยการเรียกครั้งเดียวได้ การตอบสนองจะรักษาลำดับชั้นข้อมูลเพื่อให้ผู้พัฒนาไม่ต้องเรียงร้อยข้อมูลเข้าด้วยกันบนไคลเอนต์

ซึ่งแตกต่างจากคุณสมบัติ คำขอแบบแบตช์ ที่ให้คุณสามารถสร้างการเรียก API กราฟหลายครั้งซึ่งอาจไม่มีความเกี่ยวข้องกันในหนึ่งคำขอ

ต่อไปนี้คือรูปแบบทั่วไปของรูปแบบการขยายฟิลด์:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level> ในกรณีที่เป็นหนึ่งหรือหลายฟิลด์หรือขอบ (ที่แยกด้วยเครื่องหมายจุลภาค) ของโหนดหลัก <second-level> เป็นหนึ่งหรือหลายฟิลด์หรือขอบ (ที่แยกด้วยเครื่องหมายจุลภาค) ของโหนดระดับที่หนึ่ง

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

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

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

เราจะสามารถขยายได้อีกเล็กน้อย โดยสำหรับแต่ละอ็อบเจ็กต์อัลบั้ม ให้เรียกใช้สองรูปภาพแรกและผู้ที่ถูกแท็กในแต่ละภาพด้วย:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

ตอนนี้คุณจะขยายต่อไปได้อีกโดยการเรียกใช้ชื่อของแต่ละรูปภาพ, URL ของรูป และผู้ที่ถูกแท็ก:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

ลองมาดูกันที่ตัวอย่างการใช้งานการแบ่งหน้าโดยอิงจากเคอร์เซอร์:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

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

การตัดขวางผลลัพธ์ที่แบ่งหน้า

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

การแบ่งหน้าโดยอิงจากเคอร์เซอร์

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

เมื่ออ่านจุดเชื่อมโยงหนึ่งที่รองรับการแบ่งหน้าโดยเคอร์เซอร์ คุณจะเห็นการตอบสนอง JSON ต่อไปนี้คือ:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

จุดเชื่อมโยงที่แบ่งหน้าโดยเคอร์เซอร์รองรับพารามิเตอร์ต่อไปนี้

  • before : นี่คือเคอร์เซอร์ที่ชี้ไปยังจุดเริ่มต้นของเพจของข้อมูลที่ส่งกลับคืน
  • after : นี่คือเคอร์เซอร์ที่ชี้ไปยังจุดสุดท้ายของเพจของข้อมูลที่ส่งกลับคืน
  • limit : จำนวนอ็อบเจ็กต์สูงสุดที่อาจถูกส่งคืน การสืบค้นอาจส่งคืนค่าที่น้อยกว่า limit เนื่องจากการฟิลเตอร์ อย่าหวังให้จำนวนผลลัพธ์ที่น้อยกว่าค่าlimitให้เป็นตัวระบุว่าการสืบค้นของคุณถึงปลายรายการข้อมูลแล้ว ให้ใช้การแยก next ออกแทน ตามที่ระบุไว้ด้านล้าง ตัวอย่างเช่น หากคุณตั้งค่า limit ไว้ที่ 20 จะพบ 20 ออบเจ็กต์ แต่จะแสดงเพียง 9 ออบเจกต์เท่านั้น เนื่องจากการฟิลเตอร์ความเป็นส่วนตัว หากคุณตั้งค่า limit ใหม่เป็น 40 ออบเจ็กต์ จะพบ 40 ออบเจ็กต์ แต่เช่นเดียวกัน จะส่งค่าเพียง 12 ออบเจ็กต์เท่านั้นตามการฟิลเตอร์ หากไม่มีผลการค้นหาใดๆ จะไม่มีหมายเลขหน้าและตัวบ่งชี้ที่บ่งบอกว่ามีรายการเพิ่มเติม แม้คุณอาจจะพบรายการเพิ่มเติมได้หากเพิ่ม limit ก็ตาม จุดเชื่อมโยงบางจุดเชื่อมโยงยังอาจมีค่าสูงสุดของlimitด้วยเหตุผลด้านประสิทธิภาพ
  • next : ปลายทาง API กราฟที่จะส่งกลับเพจถัดไปของข้อมูล หากไม่ระบุ นี่จะเป็นเพจสุดท้ายของข้อมูล เนื่องจากวิธีการแบ่งหน้าทำงานร่วมกับการมองเห็นได้และความเป็นส่วนตัว จึงเป็นไปได้ว่าเพจอาจว่างแต่มีลิงก์การแบ่งเป็นหน้า 'ถัดไป' หยุดการแบ่งหน้าเมื่อลิงก์ 'ถัดไป' ไม่ปรากฏอีก
  • previous : ปลายทาง API กราฟที่จะส่งกลับเพจก่อนหน้าของข้อมูล หากไม่ระบุ นี่จะเป็นเพจแรกของข้อมูล

อย่าจัดเก็บเคอร์เซอร์ เคอร์เซอร์อาจไม่สามารถใช้งานได้ในเวลาอันสั้นหากมีการเพิ่มหรือลบรายการต่างๆ

การแบ่งหน้าโดยอิงจากเวลา

การแบ่งหน้าด้วยเวลานั้นใช้เพื่อการเรียกดูข้อมูลผลลัพธ์โดยใช้ประทับเวลา Unix ซึ่งชี้ไปที่เวลาที่เจาะจงในรายการของข้อมูล

เมื่อใช้ปลายทางที่ใช้การแบ่งหน้าด้วยเวลา คุณจะเห็นการตอบสนอง JSON ต่อไปนี้:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

จุดเชื่อมโยงที่แบ่งหน้าด้วยเวลารองรับพารามิเตอร์ต่อไปนี้:

  • until : ประทับเวลา Unix หรือค่าข้อมูล strtotime ที่ชี้ไปยังปลายทางของช่วงของข้อมูลที่อิงตามเวลา
  • since : ประทับเวลา Unix หรือค่าข้อมูล strtotime ที่ชี้ไปยังจุดเริ่มต้นของช่วงของข้อมูลที่อิงตามเวลา
  • limit : จำนวนอ็อบเจ็กต์สูงสุดที่อาจถูกส่งคืน การสืบค้นอาจส่งคืนค่าที่น้อยกว่าlimitเนื่องจากการฟิลเตอร์ อย่าหวังให้จำนวนผลลัพธ์ที่น้อยกว่าค่าlimitให้เป็นตัวระบุว่าการสืบค้นของคุณถึงปลายรายการข้อมูลแล้ว ให้ใช้การแยก next ออกแทน ตามที่ระบุไว้ด้านล้าง ตัวอย่างเช่น หากคุณตั้งค่าlimitไว้ที่ 10 และคุณได้ผลลัพธ์ 9 รายการ อาจมีข้อมูลมากกว่าที่แสดงแต่มีรายการหนึ่งรายการที่ถูกลบออกเนื่องจากการฟิลเตอร์ความเป็นส่วนตัว จุดเชื่อมโยงบางจุดเชื่อมโยงยังอาจมีค่าสูงสุดของlimitด้วยเหตุผลด้านประสิทธิภาพ การเรียก API จะส่งกลับลิงก์การแบ่งหน้าที่ถูกต้องในทุกกรณี
  • next : ปลายทาง API กราฟที่จะส่งกลับเพจถัดไปของข้อมูล
  • previous : ปลายทาง API กราฟที่จะส่งกลับเพจก่อนหน้าของข้อมูล

สำหรับผลลัพธ์ที่สอดคล้องกัน ให้ระบุทั้งพารามิเตอร์ since และ until อีกทั้งยังขอแนะนำว่าความต่างของเวลาสูงสุดควรจะไม่เกิน 6 เดือน

การแบ่งหน้าโดยอิงค่าออฟเซ็ต

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

จุดเชื่อมโยงที่แบ่งหน้าแบบออฟเซ็ตรองรับพารามิเตอร์ต่อไปนี้:

  • offset : พารามิเตอร์นี้จะออฟเซ็ตจุดเริ่มต้นของแต่ละหน้าด้วยจำนวนที่กำหนด
  • limit : จำนวนอ็อบเจ็กต์สูงสุดที่อาจถูกส่งคืน การสืบค้นอาจส่งคืนค่าที่น้อยกว่าlimitเนื่องจากการฟิลเตอร์ อย่าหวังให้จำนวนผลลัพธ์ที่น้อยกว่าค่าlimitให้เป็นตัวระบุว่าการสืบค้นของคุณถึงปลายรายการข้อมูลแล้ว ให้ใช้การแยก next ออกแทน ตามที่ระบุไว้ด้านล้าง ตัวอย่างเช่น หากคุณตั้งค่าlimitไว้ที่ 10 และคุณได้ผลลัพธ์ 9 รายการ อาจมีข้อมูลมากกว่าที่แสดงแต่มีรายการหนึ่งรายการที่ถูกลบออกเนื่องจากการฟิลเตอร์ความเป็นส่วนตัว จุดเชื่อมโยงบางจุดเชื่อมโยงยังอาจมีค่าสูงสุดของlimitด้วยเหตุผลด้านประสิทธิภาพ การเรียก API จะส่งกลับลิงก์การแบ่งหน้าที่ถูกต้องในทุกกรณี
  • next : ปลายทาง API กราฟที่จะส่งกลับเพจถัดไปของข้อมูล หากไม่ระบุ นี่จะเป็นเพจสุดท้ายของข้อมูล เนื่องจากวิธีการแบ่งหน้าทำงานร่วมกับการมองเห็นได้และความเป็นส่วนตัว จึงเป็นไปได้ว่าเพจอาจว่างแต่มีลิงก์การแบ่งเป็นหน้า 'ถัดไป' หยุดการแบ่งหน้าเมื่อลิงก์ 'ถัดไป' ไม่ปรากฏอีก
  • previous : ปลายทาง API กราฟที่จะส่งกลับเพจก่อนหน้าของข้อมูล หากไม่ระบุ นี่จะเป็นเพจแรกของข้อมูล

โปรดทราบว่าหากมีการเพิ่มอ็อบเจ็กต์ใหม่ไปยังรายการที่มีการแบ่งเป็นหน้า เนื้อหาของแต่ละหน้าที่อิงค่าออฟเซ็ตจะเปลี่ยนไป

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

การสร้างคำขอขนาดใหญ่

ปลายทาง API กราฟบางจุดสามารถรับพารามิเตอร์ที่มีขนาดใหญ่มากได้ หากคำขอของคุณมีขนาดใหญ่กว่าหลายพันอักขระ คุณอาจเริ่มเห็นข้อผิดพลาดของเซิร์ฟเวอร์เนื่องจากเซิร์ฟเวอร์ของเราจะปฏิเสธคำขอ GET ขนาดใหญ่มาก

สำหรับหลักปฏิบัติที่ดีที่สุดสำหรับคำขอขนาดใหญ่ ให้ใช้คำขอ POST แทนคำขอ GET และเพิ่มพารามิเตอร์ method=GET หากคุณดำเนินการนี้ POST จะได้รับการแปลผลว่าเป็น GET

การสร้างคำขอจำนวนมาก

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

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

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

คำขอการอ่าน ID หลายคำขอ

คุณสามารถสร้างคำขอ GET เดียวที่สามารถดึงข้อมูลหลายโหนดได้โดยการใช้ปลายทาง ?ids ที่มี ID อ็อบเจ็กต์ของโหนดเหล่านั้น ตัวอย่างเช่น การค้นหาใน เพจ Facebook Developers และสำหรับผู้ใช้เซสชั่นปัจจุบันในคำขอครั้งเดียว คุณสามารถใช้การเรียก API กราฟต่อไปนี้ได้:

GET graph.facebook.com
  /?ids=platform,me

ซึ่งเทียบเท่ากับแต่ละคำขอ API ต่อไปนี้:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

ข้อมูลที่ส่งกลับจะมีลักษณะดังนี้:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

อีกทั้งยังสามารถทำงานร่วมกับจุดเชื่อมโยงตราบเท่าที่ ID ที่ขอทั้งหมดมีจุดเชื่อมโยงที่ขอ ตัวอย่างเช่น:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

เทียบเท่ากับแต่ละคำขอ API ต่อไปนี้:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

ข้อมูลที่ส่งกลับจะมีลักษณะดังนี้:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

โปรดทราบว่า ขณะที่กำลังฟิลเตอร์ฟิลด์ การขยายฟิลด์และการจำกัดจะทำงานด้วยการค้นหา ID จำนวนมาก คุณจะได้รับข้อผิดพลาดหากหนึ่งในอ็อบเจ็กต์ไม่มีฟิลด์ใดๆ ที่ขอ ตัวอย่างเช่น หากคุณจะค้นหาเพจและผู้ใช้โดยใช้วิธีการนี้ จากนั้นฟิลเตอร์บน fields=id,picture,gender คำขอจะไม่สำเร็จเนื่องจากเพจไม่มีฟิลด์ gender

การตรวจสอบภายใน

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

GET graph.facebook.com
  /{node-id}?
    metadata=1

JSON ที่ได้จะมีคุณสมบัติ metadata ที่แสดงรายการของจุดเชื่อมโยงที่รองรับทั้งหมดสำหรับโหนดนั้นๆ:

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

การเผยแพร่

โหนดส่วนใหญ่ใน API กราฟมีจุดเชื่อมโยงที่สามารถเผยแพร่เป้าหมายได้ เช่น /{user-id}/feed หรือ /{album-id}/photos การเผยแพร่ด้วย API กราฟทั้งหมดนั้นดำเนินการด้วยคำขอ HTTP POST ไปยังจุดเชื่อมโยงที่เกี่ยวข้องพร้อมกับพารามิเตอร์ที่จำเป็นที่รวมอยู่ด้วย ตัวอย่างเช่น หากต้องการโพสต์ในนามใครคนหนึ่ง คุณอาจสร้างคำขอ HTTP POST เช่นด้านล่างนี้:

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

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

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

คู่มือ สถานการณ์การใช้งานที่พบบ่อยสำหรับ API กราฟ มีข้อมูลเพิ่มเติมสำหรับสถานการณ์การเผยแพร่ที่พบบ่อยสองสามรายการ

การสร้างคำขอจำนวนมาก

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

อ่าน-หลังจาก-เขียน

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

การอัพเดต

การอัพเดต API กราฟทั้งหมดนั้นดำเนินการด้วยคำขอ HTTP POST ไปยังโหนดที่เกี่ยวข้องพร้อมกับพารามิเตอร์ที่จำเป็นรวมไปด้วย:

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

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

อ่าน-หลังจาก-เขียน

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

การลบ

ลบโหนดออกจากราฟโดยส่งคำขอ HTTP DELETE ไปยังโหนดเหล่านั้น:

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

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

เพื่อรองรับไคลเอนต์ที่ไม่รองรับวิธีการ HTTP ทั้งหมด คุณสามารถเลือกที่จะออกคำขอ POST ไปยังจุดสิ้นสุดพร้อมอาร์กิวเมนต์เพิ่มเติม method=delete เพื่อแทนที่วิธีการ HTTP ได้ ตัวอย่างเช่น คุณสามารถลบความคิดเห็นโดยการออกคำขอต่อไปนี้:

POST graph.facebook.com
  /{comment-id}?
    method=delete

อ่าน-หลังจาก-เขียน

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

วิธีใช้คุณสมบัตินี้ ให้รวมพารามิเตอร์ fields จากคำขอของคุณและระบุช่องที่คุณต้องการส่งกลับ ตัวอย่างเช่น หากต้องการเผยแพร่ข้อความ “สวัสดี” ไปยังฟีดของผู้ใช้ คุณสามารถสร้างคำขอได้ดังนี้:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

การดำเนินการนี้จะส่งกลับช่องที่กำหนดมาในรูปแบบ JSON ดังเช่น:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

อ้างอิงถึงเอกสารอ้างอิงของแต่ละปลายทางเพื่อดูว่าได้รองรับ อ่าน-หลังจาก-เขียน หรือไม่ และดูว่าช่องใดสามารถใช้งานได้บ้าง

ข้อผิดพลาด

หากการอ่านเกิดข้อผิดพลาดขึ้นด้วยเหตุผลก็ตาม (ตัวอย่างเช่น การขอช่องที่ไม่มีอยู่จริง), API กราฟจะตอบสนองด้วยการตอบรับข้อผิดพลาดมาตรฐาน นอกจากนี้ การตอบสนองจะรวมถึงoriginal_responseทรัพย์สินที่มีค่าปลายทางส่งกลับขึ้นกับความสำเร็จ

ตัวอย่างเช่น คำขอนี้มีช่องที่ไม่ถูกต้อง:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

การตอบสนองอาจเป็นเช่นนี้:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

คุณสามารถค้นหาอ็อบเจ็กต์สาธารณะได้หลายอ็อบเจ็กต์ในกราฟสังคมด้วยปลายทาง /search รูปแบบคำสั่งสำหรับการค้นหาคือ:

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

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

ชนิดของการค้นหาที่มีให้บริการ

เรารองรับประเภทการค้นหาต่อไปนี้:

ประเภท คำอธิบาย ค่า `q`

user

ค้นหาบุคคล (หากบุคคลนั้นอนุญาตให้ค้นหาชื่อของตนได้)

ชื่อ

page

ค้นหาเพจ

ชื่อ

event

ค้นหากิจกรรม

ชื่อ

group

ค้นหากลุ่ม

ชื่อ

place

ค้นหาสถานที่ คุณสามารถจำกัดการค้นหาให้แคบลงตามตำแหน่งที่ตั้งและระยะทางที่ระบุได้โดยการเพิ่มพารามิเตอร์ center (พร้อมละติจูดและลองจิจูด) และพารามิเตอร์ distance (ในหน่วยเมตร) ที่จะระบุหรือไม่ก็ได้ ดังนี้:

ชื่อ

placetopic

ส่งกลับรายการหัวข้อเพจของสถานที่ที่เป็นไปได้พร้อม ID ใช้กับพารามิเตอร์ topic_filter=all เพื่อให้ได้รายการเต็ม

ไม่มี

ad_*

ชุดรวบรวมตัวเลือกการค้นหาต่างๆ ที่สามารถใช้ในการค้นหาตัวเลือกในการกำหนดเป้าหมายได้

ดูตัวเลือกการกำหนดเป้าหมาย

ตัวอย่าง:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

การจัดการข้อผิดพลาด

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

การรับรหัสข้อผิดพลาด

การตอบสนองต่อไปนี้แสดงถึงการตอบสนองข้อผิดพลาดที่พบบ่อยที่เกิดจากคำขอ API ที่ล้มเหลว:

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: คำอธิบายข้อผิดพลาดที่ผู้อ่านสามารถอ่านได้
  • code: รหัสข้อผิดพลาด ค่าทั่วไปจะแสดงรายการที่ด้านล่างพร้อมกับเทคนิคการกู้คืนทั่วไป
  • error_subcode: ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาด ค่าทั่วไปจะแสดงรายการที่ด้านล่าง
  • error_user_msg: ข้อความที่แสดงต่อผู้ใช้ ภาษาของข้อความจะอิงตามระบบภาษาของคำขอ API
  • error_user_title: ชื่อเรื่องของกล่องโต้ตอบหากแสดงอยู่ ภาษาของข้อความจะอิงตามระบบภาษาของคำขอ API
  • fbtrace_id: ตัวระบุการรองรับภายใน เมื่อทำการรายงานจุดบกพร่องที่เกี่ยวข้องกับการเรียก API กราฟ ให้รวม fbtrace_id มาด้วยเพื่อช่วยเราค้นหาข้อมูลบันทึกสำหรับการแก้ไขจุดบกพร่อง

รหัสข้อผิดพลาด

โค้ดหรือชนิด ชื่อ สิ่งที่ต้องดำเนินการ

OAuthException

หากไม่มีโค้ดย่อย นั่นหมายความว่าสถานะการเข้าสู่ระบบหรือโทเค็นการเข้าถึงหมดอายุ ถูกลบออก หรือไม่ถูกต้อง รับโทเค็นการเข้าถึงใหม่

หากมีโค้ดย่อย โปรดดูโค้ดย่อย

102

เซสชั่น API

หากไม่มีโค้ดย่อย นั่นหมายความว่าสถานะการเข้าสู่ระบบหรือโทเค็นการเข้าถึงหมดอายุ ถูกลบออก หรือไม่ถูกต้อง รับโทเค็นการเข้าถึงใหม่

หากมีโค้ดย่อย โปรดดูโค้ดย่อย

1

API ที่ไม่รู้จัก

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

2

การบริการ API

ปัญหาของการใช้งานไม่ได้ชั่วคราว รอสักครู่แล้วลองดำเนินการอีกครั้ง

4

การเรียก API มากเกินไป

ปัญหาชั่วคราวเนื่องมาจากการควบคุมปริมาณ รอสักครู่แล้วลองดำเนินการอีกครั้ง หรือตรวจสอบปริมาณคำขอ API ของคุณ

17

การเรียก API โดยผู้ใช้มากเกินไป

ปัญหาชั่วคราวเนื่องมาจากการควบคุมปริมาณ รอสักครู่แล้วลองดำเนินการอีกครั้ง หรือตรวจสอบปริมาณคำขอ API ของคุณ

10

ปฏิเสธการให้สิทธิ์การอนุญาตของ API

ไม่ได้รับสิทธิ์การอนุญาตหรือสิทธิ์ถูกนำออกไปแล้ว จัดการกับสิทธิ์การอนุญาตที่ไม่มีอยู่

190

โทเค็นการเข้าถึงหมดอายุแล้ว

รับโทเค็นการเข้าถึงใหม่

200-299

สิทธิ์การอนุญาต API (หลายค่าขึ้นอยู่กับสิทธิ์การอนุญาต)

ไม่ได้รับสิทธิ์การอนุญาตหรือสิทธิ์ถูกนำออกไปแล้ว จัดการกับสิทธิ์การอนุญาตที่ไม่มีอยู่

341

ถึงขีดจำกัดของแอพพลิเคชั่น

ปัญหาชั่วคราวเนื่องมาจากการใช้งานไม่ได้หรือการควบคุมปริมาณ รอสักครู่แล้วลองดำเนินการอีกครั้ง หรือตรวจสอบปริมาณคำขอ API ของคุณ

368

บล็อกไว้ชั่วคราวเนื่องจากฝ่าฝืนนโยบาย

รอสักครู่แล้วลองดำเนินการอีกครั้ง

506

โพสต์ซ้ำ

ไม่สามารถเผยแพร่โพสต์ซ้ำติดกันได้ เปลี่ยนเนื้อหาของโพสต์แล้วลองอีกครั้ง

1609005

ข้อผิดพลาดกับลิงก์ในการโพสต์

เกิดปัญหาในการดึงข้อมูลจากลิงก์ที่ให้ ให้ตรวจสอบ URL แล้วลองอีกครั้ง

โค้ดย่อยข้อผิดพลาดในการยืนยันตัวตน

โค้ด ชื่อ สิ่งที่ต้องดำเนินการ

458

ยังไม่ได้ติดตั้งแอพ

ผู้ใช้ไม่ได้เข้าสู่ระบบแอพของคุณ รับรองความถูกต้องของผู้ใช้ซ้ำอีกครั้ง

459

ผู้ใช้ได้ทำการเช็คพอยท์

ผู้ใช้ต้องเข้าสู่ระบบที่ https://www.facebook.com หรือ https://m.facebook.com เพื่อแก้ไขปัญหา

460

มีการเปลี่ยนรหัสผ่าน

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

463

หมดอายุ

สถานะการเข้าสู่ระบบหรือโทเค็นการเข้าถึงหมดอายุ ถูกลบออก หรือใช้ไม่ได้ จัดการโทเค็นการเข้าถึงที่หมดอายุ

464

ผู้ใช้ไม่ได้รับการยืนยัน

ผู้ใช้ต้องเข้าสู่ระบบที่ https://www.facebook.com หรือ https://m.facebook.com เพื่อแก้ไขปัญหา

467

โทเค็นการเข้าถึงใช้ไม่ได้

โทเค็นการเข้าถึง หมดอายุ ถูกลบออก หรือใช้ไม่ได้ จัดการโทเค็นการเข้าถึงที่หมดอายุ

พารามิเตอร์ที่ซับซ้อน

ชนิดของพารามิเตอร์ส่วนใหญ่เป็นแบบเรียบง่ายตรงไปตรงมา เช่น string และ int แต่ยังคงมีชนิด list และ object ที่สามารถระบุได้ในคำขอ

ชนิด list ถูกระบุในหลักโครงสร้าง JSON ตัวอย่างเช่น: ["firstitem", "seconditem", "thirditem"]

ชนิด object ถูกระบุในหลักโครงสร้าง JSON ด้วยเช่นกัน ตัวอย่างเช่น: {"firstkey": "firstvalue", "secondKey": 123}

การแก้ไขจุดบกพร่องคำขอ API

โหมดแก้ไขจุดบกพร่อง API กราฟ

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

ในการเปิดใช้งานโหมดแก้ไขจุดบกพร่อง ให้ใช้พารามิเตอร์สตริงสืบค้นข้อมูล debug ตัวอย่างเช่น:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

หากไม่ได้รับสิทธิ์การอนุญาต user_friends สิ่งนี้จะสร้างการตอบสนองต่อไปนี้:

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

ค่าพารามิเตอร์ debug สามารถตั้งค่าเป็น "ทั้งหมด" หรือระดับความรุนแรงที่ร้องขอที่น้อยที่สุดที่สอดคล้องกับ type ของข้อความ:

ค่าพารามิเตอร์การแก้ไขจุดบกพร่อง สิ่งที่จะส่งกลับคืน

ทั้งหมด

ข้อความแก้ไขจุดบกพร่องทั้งหมดที่มี

ข้อมูล

ข้อความแก้ไขจุดบกพร่องที่มีชนิด ข้อมูลและคำเตือน

คำเตือน

ข้อความแก้ไขจุดบกพร่องที่มีชนิด คำเตือน เท่านั้น

ข้อมูลการแก้ไขจุดบกพร่อง (ถ้ามี) ที่ส่งคืนเป็นอ็อบเจ็กต์ JSON ภายใต้คีย์ __debug__ ที่มีอาร์เรย์ messages ทุกองค์ประกอบของอาร์เรย์นี้คืออ็อบเจ็กต์ JSON ที่ประกอบด้วยฟิลด์ต่อไปนี้:

เขตข้อมูล ชนิดข้อมูล คำอธิบาย

ข้อความ

สตริง

ข้อความ

ประเภท

สตริง

ความรุนแรงของข้อความ

ลิงก์

สตริง

[ระบุหรือไม่ก็ได้] URL ชี้ไปที่ข้อมูลที่สัมพันธ์กัน

คุณยังสามารถใช้โหมดแก้ไขจุดบกพร่องกับ “Graph API Explorer” ได้ด้วย

การตรวจสอบเวอร์ชั่นที่ใช้โดยคำขอ API

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

API กราฟจะมีส่วนหัวการตอบสนองด้วยการตอบสนองใดๆ ที่เรียกว่า facebook-api-version ที่บ่งชี้เวอร์ชั่นที่แน่นอนของ API ที่สร้างการตอบสนอง ตัวอย่างเช่น การเรียก API กราฟที่สร้างคำขอด้วยเวอร์ชั่น 2.0 จะมีส่วนหัว HTTP ดังต่อไปนี้:

facebook-api-version:v2.0

ส่วนหัว facebook-api-version นี้ทำให้คุณกำหนดได้ว่าการเรียก API กำลังจะถูกส่งกลับจากเวอร์ชั่นที่คุณคาดหวังหรือไม่

ข้อมูลการแก้ไขจุดบกพร่องสำหรับการรายงานจุดบกพร่อง

หากคุณจำเป็นต้องรายงานจุดบกพร่องใน API กราฟ เราได้รวมส่วนหัวคำขอเพิ่มเติมที่คุณควรส่งพร้อมกับรายงานจุดบกพร่องของคุณเพื่อช่วยเราในการชี้จุดปัญหาและซ้ำขึ้นมาใหม่ได้ ส่วนหัวของคำขอเหล่านี้คือ X-FB-Debug, x-fb-rev และ X-FB-Trace-ID