Instagram 平台
返回中文(香港)
這份文件已更新。
中文(香港) 的翻譯尚未完成。
英文更新時間：10月16日

Instagram 媒體

代表 Instagram 相簿、相片或影片（上載的影片、直播視像、使用 Instagram TV 應用程式建立的影片、連續短片或限時動態）。

由 2024 年 6 月 3 日起，您可使用 boost_eligibility_info 欄位，以方便快捷地判斷媒體是否符合資格以廣告形式加強推廣；您亦可用 boost_ads_list 來追蹤有關廣告的過往加強推廣 Instagram 廣告資料。請參閱網誌以了解詳情。僅適用於 Instagram Graph API。

建立

不支援這項操作。

讀取

GET /<IG_MEDIA_ID>

獲取 Instagram 媒體的欄位和關係連線。

限制

  • 傳回彙總值的欄位不會包含由廣告帶來的資料。例如，comments_count 會計算相片上的留言，但不會計算採用該相片的廣告之留言。
  • 除非應用程式用戶亦可在應用程式執行管理員級別任務，否則說明文字不能包含 @ 符號。
  • 某些欄位（如 permalink）不適用於相簿中的相片（子物件）。
  • 直播視像 Instagram 媒體僅能在直播時被讀取。
  • 此 API 僅傳回 Instagram 專業帳戶所擁有媒體的資料。此 API 不可用於獲取 Instagram 個人帳戶所擁有媒體的資料。

要求語法

GET https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?fields=<LIST_OF_FIELDS>
  &access_token=<ACCESS_TOKEN>

路徑參數

預留位置值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

此為必要項目。待發佈媒體的編號。

查詢字串參數

鍵值預留位置值

access_token

<ACCESS_TOKEN>

此為必要項目。應用程式用戶的用戶存取憑證

fields

<LIST_OF_FIELDS>

您想系統傳回的欄位逗號分隔清單。

欄位

可透過欄位擴充功能讀取的公開欄位。

欄位說明

boost_ads_list

提供與自主媒體關聯的所有 Instagram 廣告資訊的概述，其中包括相關的廣告編號和廣告刊登狀態。僅適用於 Instagram Graph API。

boost_eligibility_info

此欄位提供相關資訊，說明以廣告形式發佈 Instagram 媒體時的加強推廣資格，以及其他詳細資訊（如果媒體不符合資格）。僅適用於 Instagram Graph API。

caption
公開

說明文字。不包括相簿子物件。不包括 @ 符號，除非在已連結用於建立此說明文字的 Instagram 帳戶之 Facebook 專頁上，應用程式用戶可以執行管理員級別的任務（僅限 Instagram Graph API）。

comments_count
公開

媒體的留言數目。不包括相簿子媒體的留言及媒體說明文字。包括對留言的回覆。

copyright_check_information.status

傳回 status 和 matches_found 物件

狀態物件說明

status

  • completed：已完成偵測程序
  • error：偵測期間發生錯誤
  • in_progress：偵測程序進行中
  • not_started：未啟動偵測程序

matches_found

設定為下列其中一項：

  • 如果影片沒有侵犯版權，則設定為 false；
  • 如果影片有侵害版權，則設定為 true

如果影片侵犯版權，則系統會將傳回 copyright_matches，並附上版權內容的物件陣列、影片中侵犯版權的時間點，以及為降低侵犯版權事件影響所採取的緩解措施。

copyright_matches 物件說明

author

受版權保護的影片之作者

content_title

受版權保護的影片名稱

matched_segments

帶有下列鍵值組合的物件列陣：* duration_in_seconds—侵犯版權的內容所在的秒數 * segment_type – AUDIO 或 VIDEO * start_time_in_seconds—設定為影片的開始時間

owner_copyright_policy

傳回的物件包括：

  • name：版權擁有者政策的名稱

  • actions：action 物件列陣，附以所採取的緩解措施，有關措施按版權擁有者的政策而定。其中可能包括為不同地方採取不同緩解措施。

    • action：為降低侵犯版權事件影響所採取的緩解措施。採取的緩解措施可能因國家／地區而異。可以是下列其中一個值：
      • BLOCK：封鎖影片以不向 geos 陣列中的分享對象展示
      • MUTE：向 geos 陣列中的分享對象將影片設定為靜音

id
公開

媒體編號。

is_comment_enabled

表示留言處於啟用還是停用狀態。不包括相簿子物件。

is_shared_to_feed
公開

僅適用於 Reels。如果為 true，則表示連續短片可同時顯示在動態消息和 Reels 分頁。如果為 false，則表示連續短片只可顯示在 Reels 分頁。

請注意，這兩個值都不表示連續短片是否實際顯示在 Reels 分頁，因為連續短片可能不符合資格要求或未被我們的演算法選中。有關資格條件的資訊，請參閱連續短片規格。

like_count

媒體獲得的讚好數目，包括對留言的回覆。不包括相簿子媒體的讚好數目，以及使用此媒體建立的推廣帖子所獲得的讚好數目。


如果透過其他端點或欄位擴充功能間接查詢，且媒體擁有者隱藏了讚好數目，則會省略 like_count 欄位。

media_product_type
公開

媒體的發佈平台。可以是 AD、FEED、STORY 或 REELS。僅適用於 Instagram Graph API。

media_type
公開

媒體類型。可以是 CAROUSEL_ALBUM、IMAGE 或 VIDEO。

media_url
公開

媒體網址。

如果媒體包含受版權保護的內容，或者已被標示為侵犯版權，則回應會省略 media_url 欄位。受版權保護的內容包括連續短片上的音訊。

owner
公開

建立媒體的 Instagram 用戶帳號。只會在發出查詢要求的應用程式用戶也是媒體的建立者時傳回，否則將改為傳回 username 欄位。

permalink
公開

媒體的永久網址。

shortcode
公開

媒體的短代碼。

thumbnail_url
公開

媒體縮圖網址。僅適用於 VIDEO 媒體。

timestamp
公開

以 ISO 8601 格式顯示的建立日期，採用 UTC 時間，預設為 UTC ±00:00。

username
公開

建立媒體的用戶之用戶名稱。

關係連線

可透過欄位擴充功能傳回的公開關係連線。

關係連線說明

children
公開。

代表 Instagram 媒體相簿中的一系列 Instagram 媒體物件。

collaborators

代表獲加為 Instagram 媒體物件協作者的用戶名單。僅適用於 Instagram Graph API。

comments

代表 Instagram 媒體物件的一系列 Instagram 留言。

insights

代表 Instagram 媒體物件上的社交互動衡量數據。僅適用於 Instagram Graph API。

cURL 範例

要求範例

curl -X GET \
  'https://graph.instagram.com/v21.0/17895695668004550?fields=id,media_type,media_url,owner,timestamp&access_token=IGQVJ...'

回覆範例

{
  "id": "17918920912340654",
  "media_type": "IMAGE",
  "media_url": "https://sconten...",
  "owner": {
    "id": "17841405309211844"
  },
  "timestamp": "2019-09-26T22:36:43+0000"
}

更新

POST /<IG_MEDIA_ID>

啟用或停用 Instagram 媒體的留言功能。

限制

不支援直播視像 Instagram 媒體。

Requirements

Instagram API with Instagram LoginInstagram API with Facebook Login

Access Tokens

  • Instagram User access token

Host URL

graph.instagram.com

graph.facebook.com

Login Type

Business Login for Instagram

Facebook Login for Business

Permissions
  • instagram_business_basic
  • instagram_business_manage_comments
  • instagram_basic
  • instagram_manage_comments
  • pages_read_engagement
  • pages_show_list

If the app user was granted a role via the Business Manager on the Page connected to the targeted IG User, you will also need one of:

  • ads_management
  • business_management

要求語法

POST https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?comment_enabled=<BOOL>
  &access_token=<ACCESS_TOKEN>

路徑參數

預留位置值

<API_VERSION>

API 版本。

<IG_MEDIA_ID>

此為必要項目。Instagram 媒體編號。

查詢字串參數

鍵值預留位置值

access_token

<ACCESS_TOKEN>

此為必要項目。應用程式用戶的用戶存取憑證。

comment_enabled

<BOOL>

此為必要項目。設定為 true 以啟用留言功能，或設定為 false 以停用留言功能。

cURL 範例

要求範例

curl -i -X POST \
 "https://graph.instagram.com/v21.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

回覆範例

{
  "success": true
}

刪除

不支援這項操作。