การกำหนดเวอร์ชั่น
เวอร์ชั่นปัจจุบันของ API การตลาดคือ v21.0.
แพลตฟอร์มของ Facebook มีรูปแบบการกำหนดเวอร์ชั่นหลักและแบบขยาย การเปลี่ยนแปลงที่มีผลต่อการทำงานทั้งหมดจะอยู่ในเวอร์ชั่นใหม่เมื่อมีการกำหนดเวอร์ชั่น API การตลาด และทำให้มี API หรือ SDK การตลาดได้หลายเวอร์ชั่นในเวลาเดียวกันโดยที่แต่ละเวอร์ชั่นมีฟังก์ชั่นการทำงานที่แตกต่างกัน
ผู้พัฒนาควรทำความเข้าใจล่วงหน้าเมื่อ APIหรือ SDK การตลาดจะมีการเปลี่ยนแปลง แม้คุณจะมีระยะเวลา 90 วันในการปรับตัวรับการเปลี่ยนแปลงนี้ แต่วิธีย้ายและเวลาย้ายข้อมูลไปยังเวอร์ชั่นใหม่นั้นขึ้นอยู่กับคุณ
กำหนดเวลาของเวอร์ชั่น
เมื่อมีการเผยแพร่ API การตลาดเวอร์ชั่นใหม่ เราจะรองรับ API การตลาดเวอร์ชั่นก่อนหน้าต่อไปอย่างน้อย 90 วัน คุณจะมีระยะเวลาผ่อนผันอย่างน้อย 90 วันในการย้ายไปยังเวอร์ชั่นใหม่ ในช่วงระยะเวลาผ่อนผัน 90 วัน คุณสามารถเรียกใช้ได้ทั้งเวอร์ชั่นปัจจุบันและเวอร์ชั่นที่เลิกใช้แล้ว และคุณมีระยะเวลาผ่อนผัน 90 วันในการย้ายไปยังเวอร์ชั่นใหม่ เมื่อระยะเวลาผ่อนผัน 90 วันดังกล่าวสิ้นสุดลง เวอร์ชั่นที่เลิกใช้แล้วจะหยุดทำงาน เมื่อเวอร์ชั่นไม่พร้อมใช้งาน การเรียกใช้หมายเลขเวอร์ชั่นดังกล่าวอาจล้มเหลวหรือได้รับการอัพเกรดเป็นเวอร์ชันถัดไปที่เปิดให้ใช้งาน
ตัวอย่างเช่น มีการเผยแพร่ API การตลาดเวอร์ชั่น 17.0 ในวันที่ 23 พฤษภาคม 2023 และ API การตลาดเวอร์ชั่น 16.0 จะหมดอายุในวันที่ 6 กุมภาพันธ์ 2024 ซึ่งมีเวลาอย่างน้อย 90 วันในการย้ายไปยังเวอร์ชั่นใหม่
ไทม์ไลน์ตัวอย่างมีดังต่อไปนี้ โปรดทราบว่าเราอาจไม่เผยแพร่เวอร์ชั่นใหม่เมื่อครบกำหนดระยะเวลาผ่อนผัน 90 วันของการเลิกใช้เวอร์ชั่นเก่าเสมอไป ซึ่งตัวอย่างนี้แสดงให้เห็นว่า มีการเลิกใช้เวอร์ชั่น 16.0 ไปช่วงหนึ่งก่อนเผยแพร่เวอร์ชั่น 18.0:
สำหรับ SDK จะยังมีเวอร์ชั่นหนึ่งให้ใช้ได้อยู่เสมอเนื่องจากเป็นแพ็คเกจที่ดาวน์โหลดได้ อย่างไรก็ตาม เมื่อพ้นวันหมดอายุแล้ว เวอร์ชั่นดังกล่าวอาจต้องใช้ API การตลาดหรือเมธอดที่ใช้งานไม่ได้อีกต่อไป คุณจึงควรตั้งสันนิษฐานว่า SDK ที่หมดอายุจะใช้งานไม่ได้อีกต่อไป
การส่งคำขอที่มีการกำหนดเวอร์ชั่น
ตำแหน่งข้อมูล API การตลาดทั้งหมดจะมีให้ใช้ผ่านพาธที่มีการกำหนดเวอร์ชั่น พักเวอร์ชั่นไว้ก่อนที่จุดเริ่มของพาธคำขอ ตัวอย่างเช่น:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"
วิธีนี้จะใช้ได้กับทุกเวอร์ชั่นในรูปแบบทั่วไปนี้:
https://graph.facebook.com/v{n}/{request-path}โดย n คือเวอร์ชั่นที่ต้องใช้ โปรดดูเวอร์ชั่นที่เปิดให้ใช้งานทั้งหมดได้ในบันทึกการเปลี่ยนแปลงของเรา ข้อมูลอ้างอิงของ API การตลาดทั้งหมดของเราจะให้ข้อมูลตามเวอร์ชั่น
การย้าย
การย้ายนั้นมีให้ใช้ในกรณีพิเศษที่ต้องทำการเปลี่ยนแปลงซึ่งไม่สามารถอาศัยการกำหนดเวอร์ชั่นได้ ซึ่งโดยทั่วไปแล้วจะเกิดขึ้นเมื่อมีการเปลี่ยนแปลงรูปแบบข้อมูลเบื้องหลัง ทั้งนี้การย้ายจะมีผลกับทุกเวอร์ชัน
การย้ายที่ยังอยู่ระหว่างการดำเนินการจะแสดงอยู่ในหน้าการย้ายของเรา การย้ายจะมีช่วงเวลาอย่างน้อย 90 วัน ซึ่งเป็นช่วงที่คุณต้องย้ายแอพของคุณ เมื่อช่วงเวลาดังกล่าวเริ่มต้นขึ้น พฤติกรรมหลังการย้ายจะกลายเป็นค่าเริ่มต้นสำหรับแอพใหม่ จากนั้นเมื่อช่วงการย้ายสิ้นสุดลง พฤติกรรมก่อนการย้ายจะไม่สามารถใช้งานได้อีกต่อไป
การจัดการการย้ายผ่าน API กราฟ
คุณสามารถจัดการการย้ายผ่านช่องการย้ายในโหนด /app ได้ดังนี้
คุณสามารถทำการเรียกใช้การอัพเดตจุดเชื่อมโยงเพื่อเปิดและปิดใช้งานการย้ายได้
จัดการการย้ายผ่านแดชบอร์ดของแอพ
คุณสามารถเปิดและปิดการย้ายที่มีอยู่ได้ใน "แดชบอร์ดของแอพ" ในส่วน "การตั้งค่า > การย้าย" โปรดทราบว่ารายการที่ย้ายอาจมีลักษณะไม่เหมือนกับรูปภาพที่แสดงไว้ด้านล่าง เนื่องจากในเวลาที่ต่างกัน การย้ายที่มีอยู่อาจมีความแตกต่างกันไปในแต่ละแอพ และหากคุณเห็นการย้าย Use Graph API v2.0 by default หมายความว่าเป็นการย้ายสำหรับ API กราฟ เท่านั้น ไม่ใช่ API การตลาด
การเปิดใช้งานการย้ายฝั่งไคลเอ็นต์ชั่วคราว
หากไม่ต้องการเปิดใช้งานการย้ายในแดชบอร์ดของแอพ หรือผ่าน API การตลาด คุณสามารถเพิ่มแฟล็กพิเศษให้กับการเรียกใช้ API การตลาดของคุณซึ่งตั้งค่าการย้ายแทนได้ ซึ่งแฟล็กนี้เรียกว่า migrations_override และคุณต้องกำหนด JSON Blob ที่อธิบายว่ามีการย้ายใดบ้างที่คุณต้องการเปิดหรือปิด ตัวอย่างเช่น หากคุณจะทำการเรียกใช้ที่ยังไม่ผ่านการแปลงที่คุณอาจส่งผ่าน:
http://graph.facebook.com/path?
migrations_override={"migration1":true, "migration2":false}วิธีนี้จะทำให้คุณสามารถเรียกใช้ API การตลาดใหม่ผ่านการอัพเดตของไคลเอ็นต์ได้ แทนที่จะต้องให้ผู้เรียกใช้ทุกรายอัพเดตการเรียกใช้ API การตลาดใหม่พร้อมกัน และยังมีประโยชน์อย่างยิ่งสำหรับการแก้ไขจุดบกพร่อง
คุณสามารถดูชื่อการย้ายต่างๆ เหล่านี้ได้ในโหนด /app ที่กล่าวถึงข้างต้น
การอัพเกรดเวอร์ชั่นโดยอัตโนมัติ
เนื่องจากเวอร์ชั่น API การตลาดมีการหมุนเวียนอย่างรวดเร็วทุกๆ 4 เดือนโดยประมาณ เราจึงปรับปรุงกระบวนการอัพเกรดให้มีประสิทธิภาพยิ่งขึ้น ตั้งแต่เดือนพฤษภาคม 2024 เป็นต้นไป เราจะเปิดใช้งานฟีเจอร์การอัพเกรดเวอร์ชั่นโดยอัตโนมัติสำหรับตำแหน่งข้อมูล API การตลาดที่ไม่ได้รับผลกระทบระหว่างเวอร์ชั่น ซึ่งหมายความว่าระหว่างเวอร์ชั่นที่จะเลิกใช้งานกับเวอร์ชั่นถัดไปที่จะเปิดให้ใช้งาน หากตำแหน่งข้อมูลไม่ได้รับผลกระทบ แพลตฟอร์มจะอัพเกรดการเรียกใช้เป็นเวอร์ชั่นถัดไปที่เปิดให้ใช้งาน แทนที่จะทำให้คำขอดังกล่าวล้มเหลวไปเลย การเปลี่ยนแปลงนี้ออกแบบมาเพื่อให้ประสบการณ์การใช้งาน API ราบรื่นและมีประสิทธิภาพยิ่งขึ้น
ตัวอย่างเช่น เราจะเลิกใช้งานเวอร์ชั่น 17.0 ในวันที่ 14 พฤษภาคม 2024 ตามบันทึกการเปลี่ยนแปลงของเวอร์ชั่น 18.0 ตำแหน่งข้อมูลต่อไปนี้จะได้รับผลกระทบ
POST /act_{ad-account-id}/reachfrequencypredictionsGET /act_{ad-account-id}/reachestimateGET /act_{ad-account-id}/delivery_estimatePOST /act_{ad-account-id}/adsetsPOST /{adset-id}POST /act_{ad-account-id}/saved_audiencesPOST /{saved-audience-id}POST /act_{ad-account-id}/credit_cards
หากแอพของคุณเรียกใช้ POST /{adset-id} ด้วยเวอร์ชั่น 17.0 หลังจากที่เลิกใช้งานแล้วในวันที่ 14 พฤษภาคม 2024 คำขอ API นี้จะล้มเหลวเนื่องจากระบบจะไม่ใช้การอัพเกรดโดยอัตโนมัติกับตำแหน่งข้อมูลที่ได้รับผลกระทบจากเวอร์ชั่นถัดไปที่เปิดให้ใช้งาน (นั่นคือ เวอร์ชั่น18 0)
หากแอพของคุณเรียกใช้ GET /{ad-account-id}/insights ด้วยเวอร์ชั่น 17.0 หลังจากที่เลิกใช้งานแล้ว แพลตฟอร์มจะอัพเกรดการเรียกใช้ของคุณเป็นเวอร์ชั่นถัดไปที่เปิดให้ใช้งาน (นั่นคือ เวอร์ชั่น 18.0)
หมายเหตุ: หากแอพของคุณเรียกใช้ด้วยเวอร์ชั่นที่สูงกว่าเวอร์ชั่น 17.0 อยู่แล้ว จะไม่มีอะไรเปลี่ยนแปลงในวันที่เลิกใช้งานเวอร์ชั่น
หากต้องการตรวจสอบตำแหน่งข้อมูลที่ได้รับผลกระทบในแต่ละเวอร์ชั่น โปรดดูที่บันทึกการเปลี่ยนแปลงของ API การตลาด
คำถามที่พบบ่อย
กำหนดเวลาของเวอร์ชั่น
We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.
You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.
Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.
For example:
- If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
- If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
- Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.
If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:
- If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
- If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.
- Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
- Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
การส่งคำขอที่มีการกำหนดเวอร์ชั่น
With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:
https://graph.facebook.com/v{n}/{request-path}You can know what behavior to expect out without having to manually visit your app's migration panel.
การอัพเกรดเวอร์ชั่นโดยอัตโนมัติ
The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.
No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons
- You may still need to manually upgrade endpoints being impacted by next version.
- You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
You can look up affected endpoints from Marketing API Changelog.
You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.
If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.
Example notification header
X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''