Instagram 图谱 API

The Instagram Graph API is built on the Facebook Graph API. It functions in the same way and supports the same features, with the key difference being authentication. If you are unfamiliar with the Graph API, please read our Graph API documentation before proceeding.

Instagram Graph API建立在Facebook Graph API之上。它以相同的方式运行并支持相同的功能，不同之处在于身份验证。如果您不熟悉Graph API，请先阅读我们的Graph API文档，然后再继续。

Base URL(基本网址)

All endpoints can be accessed via the graph.facebook.com host.

可以通过graph.facebook.com主机访问所有端点。

Authentication(认证方式)

All endpoint requests must include a Facebook User access token. However, unlike Facebook users, Instagram users cannot grant your app access tokens directly. Instead, they must connect their Instagram Business Account or Instagram Creator Account to a Facebook Page. Once connected, any Facebook User who is able to perform Tasks on behalf of that Page will be able to grant your app a User access token, which you can then include in API requests.

所有端点请求都必须包含Facebook 用户访问令牌。但是，与Facebook用户不同，Instagram用户无法直接授予您的应用访问令牌。相反，他们必须将其Instagram企业帐户或Instagram创建者帐户连接到Facebook Page。建立连接后，任何能够代表该页面执行任务的 Facebook用户都可以向您的应用授予用户访问令牌，然后您可以将其包含在API请求中。

Use the Facebook Login product to request User access tokens from your app's users. Note that Page tokens are not supported.

使用Facebook登录产品向您的应用程序用户请求用户访问令牌。请注意，不支持Page令牌。

Authorization(授权书)

Endpoint authorization is handled through permissions. The API uses the following permissions and features:

端点授权通过权限处理。该API使用以下权限和功能：

Refer to the reference documentation to see which permissions each endpoint requires.

请参考参考文档以查看每个端点需要哪些权限。

You can use the Facebook Login product to request permissions from your app's users. All of these permissions can be granted by app users while your app is in Development Mode. However, with the exception of pages_show_list, your app must be approved for these permissions through the App Review process before app users can grant them to your app while it is in Live Mode.

您可以使用Facebook登录产品向您的应用程序用户请求权限。当您的应用处于开发模式时，所有这些权限都可以由应用用户授予。但是，除之外pages_show_list，必须先通过“ 应用程序审查”流程批准您的应用程序具有这些权限，然后应用程序用户才能在处于实时模式的情况下将其授予您的应用程序。

Pages(页数)

Instagram users must connect their Instagram Business Account or Instagram Creator Account to a Facebook Page before your app can access the API on their behalf. Once connected, any Facebook User who is able to perform Tasks on that Page can grant your app an access token, which can then be used in API requests.

Instagram用户必须将其Instagram企业帐户或Instagram创建者帐户连接到Facebook页面，然后您的应用才能代表他们访问API。建立连接后，任何能够在该页面上执行任务的 Facebook用户都可以为您的应用授予访问令牌，然后可以在API请求中使用该令牌。

Facebook Pages can be connected to a Business or Creator account through the Page's Settings > Instagramtab.

可以通过页面的“设置”>“ Instagram”选项卡将Facebook Pages连接到企业或创建者帐户。

Tasks(任务)

Only Facebook Users who can perform Tasks on the Facebook Page connected to the Instagram Business or Creator Account can grant your app User access tokens and permissions to use the API. Note that the API does not support Business Manager System Users, or Users with Live Contributor defined roles.

只有可以在连接到Instagram业务或创建者帐户的Facebook页面上执行任务的Facebook用户才能向您的应用授予用户访问令牌和使用API的权限。请注意，该API不支持Business Manager System用户或具有Live Contributor定义角色的用户。

Permissions can be granted by Facebook Users according to the tasks they are able to perform:

Facebook用户可以根据他们能够执行的任务来授予权限：

Permission	MANAGE	CREATE_CONTENT	MODERATE	ADVERTISE	ANALYZE
instagram_basic	✔	✔	✔	✔	✔
instagram_content_publish	✔	✔
instagram_manage_comments	✔	✔	✔
instagram_manage_insights	✔	✔	✔	✔	✔

Refer to the reference documentation to see which permissions each endpoint requires.

请参考参考文档以查看每个端点需要哪些权限。

Rate Limiting(限速)

All endpoints are subject to Instagram Business Use Case rate limiting except for Business Discovery and Hashtag Search endpoints, which are subject to Platform Rate limiting.

除Business Discovery和Hashtag Search端点外，所有终结点均受Instagram业务用例速率的限制，后者受Platform Rate限制。

Webhooks(网络挂钩)

You can use Webhooks to have notifications sent to you whenever someone comments on your app users' media objects or when any of their stories expire. Refer to our Webhooks documentation to learn how to use Webhooks, then set up a webhook for the Instagram topic and subscribe to its comments and story_insights fields.

每当有人对您的应用程序用户的媒体对象发表评论或他们的任何故事过期时，您都可以使用Webhooks将通知发送给您。请参阅我们的Webhooks文档以了解如何使用Webhooks，然后为该Instagram主题设置一个Webhook 并订阅其commentsand story_insights字段。

Limitations(局限性)

ordering results is not supported
all endpoints support cursor-based pagination, but the /{user-id}/insights edge is the only endpoint that supports time-based pagination

不支持订购结果
所有端点都支持基于游标的分页，但是/{user-id}/insights edge是唯一支持基于时间的分页的端点

Getting Started(入门)

This document explains how to successfully call the Instagram Graph API with your app and get an Instagram Business or Creator Account's media objects. It assumes you are familiar with the Graph API and Facebook Login, and know how to perform REST API calls. If you do not have an app yet, you can use the Graph API Explorer instead and skip steps 1 and 2.

本文档说明了如何使用您的应用程序成功调用Instagram Graph API并获取Instagram Business或Creator帐户的媒体对象。假定您熟悉Graph API和Facebook Login，并且知道如何执行REST API调用。如果还没有应用程序，则可以改用Graph API Explorer，并跳过步骤1和2。

Before You Start(开始前的准备)

You will need access to the following:

An Instagram Business Account or Instagram Creator Account
A Facebook Page connected to that account
A Facebook Developer account that can perform Tasks on that Page
A registered Facebook App with Basic settings configured

您将需要访问以下内容：

1. Configure Facebook Login

Add the Facebook Login product to your app in the App Dashboard.

将Facebook登录产品添加到App Dashboard中的应用程序中。

You can leave all settings on their defaults. If you are implementing Facebook Login manually (which we don't recommend), enter your redirect_uri in the Valid OAuth redirect URIs field. If you will be using one of our SDKs, you can leave it blank.

您可以将所有设置保留为默认值。如果您正在手动实施Facebook登录（我们不建议这样做），请redirect_uri在“ 有效OAuth重定向URI”字段中输入您的身份。如果您将使用我们的SDK之一，则可以将其留空。

2. Implement Facebook Login(实施Facebook登录)

Follow our Facebook Login documentation for your platform and implement Facebook Login into your app. Set up your implementation to request these permissions:

请遵循我们针对您平台的Facebook登录文档，并在您的应用程序中实现Facebook登录。设置您的实现以请求以下权限：

3. Get a User Access Token(获取用户访问令牌)

Once you've implemented Facebook Login, make sure you are signed into your Facebook Developer account, then access your app and trigger the Facebook Login modal. Remember, your Facebook Developer account must be able to perform Tasks on the Facebook Page connected to the Instagram account you want to query.

实施Facebook登录后，请确保您已登录Facebook开发人员帐户，然后访问您的应用并触发Facebook登录模式。请记住，您的Facebook开发者帐户必须能够在连接到要查询的Instagram帐户的Facebook页面上执行任务。

Once you have triggered the modal, click OK to grant your app the instagram_basic and pages_show_listpermissions.

The API should return a User access token. Capture the token so your app can use it in the next few queries. If you are using the Graph API Explorer, it will be captured automatically and displayed in the Access Token field for reference:

触发模式后，单击“ 确定”向您的应用授予instagram_basic和pages_show_list权限。

API应该返回用户访问令牌。捕获令牌，以便您的应用可以在接下来的几个查询中使用它。如果您使用的是Graph API Explorer，它将被自动捕获并显示在“ 访问令牌”字段中，以供参考：

4. Get the User's Pages(获取用户页面)

Query the GET /me/accounts endpoint (this translates to GET /{user-id}/accounts, which perform a GETon the Facebook User node, based on your access token).

查询GET /me/accounts端点（这将转换为，根据您的访问令牌在Facebook User节点上GET /{user-id}/accounts执行）。GET

curl -i -X GET

"https://graph.facebook.com/v4.0/me/accounts?access_token={access-token}"

This should return a collection of Facebook Pages that the current Facebook User can perform the MANAGE, CREATE_CONTENT, MODERATE, or ADVERTISE tasks on:

这应返回Facebook网页的集合，目前Facebook的用户可以执行的MANAGE，CREATE_CONTENT，MODERATE，或ADVERTISE在任务：

{

"data": [

{

"access_token": "EAAJjmJ...",

"category": "App Page",

"category_list": [

{

"id": "2301",

"name": "App Page"

}

"name": "Metricsaurus",

"id": "134895793791914", // capture the Page ID

"tasks": [

"ANALYZE",

"ADVERTISE",

"MODERATE",

"CREATE_CONTENT",

"MANAGE"

]

}

]

}

Capture the ID of the Facebook Page that's connected to the Instagram account that you want to query. Keep in mind that your app users may be able to perform tasks on multiple pages, so you eventually will have to introduce logic that can determine the correct Page ID to capture (or devise a UI where your app users can identify the correct Page for you).

捕获连接到要查询的Instagram帐户的Facebook页面的ID。请记住，您的应用程序用户可能能够在多个页面上执行任务，因此您最终将不得不引入可以确定要捕获的正确页面ID的逻辑（或设计一个UI，您的应用程序用户可以在其中为您标识正确的页面）。

5. Get the Page's Instagram Business Account(获取页面的Instagram企业账户)

Use the Page ID you captured to query the GET /{page-id}?fields=instagram_business_accountendpoint:

使用您捕获的页面ID来查询GET /{page-id}?fields=instagram_business_account端点：

curl -i -X GET

"https://graph.facebook.com/v4.0/134895793791914?fields=instagram_business_account&access_token={access-token}"

This should return the IG User — an Instagram Business or Creator Account — that's connected to the Facebook Page.

这应该返回已连接到Facebook页面的IG用户（Instagram企业或创建者帐户）。

{

"instagram_business_account": {

"id": "17841405822304914" // Connected IG User ID

"id": "134895793791914" // Facebook Page ID

}

Capture the IG User ID.捕获IG用户 ID。

6. Get the Instagram Business Account's Media Objects(获取Instagram商业帐户的媒体对象)

Use the IG User ID you captured to query the GET /{ig-user-id}/media endpoint:

使用捕获的IG用户 ID来查询GET /{ig-user-id}/media端点：

curl -i -X GET

"https://graph.facebook.com/v4.0/17841405822304914/media?access_token={access-token}"

This should return the IDs of all the IG Media objects on the IG User:

这应该返回IG用户上所有IG媒体对象的ID ：

{

"data": [

{

"id": "17918195224117851"

{

"id": "17895695668004550"

{

"id": "17899305451014820"

{

"id": "17896450804038745"

{

"id": "17881042411086627"

{

"id": "17869102915168123"

}

"paging": {

"cursors": {

"before": "QVFIUkdGRXA2eHNNTUs4T1ZAXNGFxQTAtd3U4QjBLd1B2NXRMM1NkcnhqRFdBcEUzSDVJZATFoLWtXMWZAGU2VrRTk2RHVtTVlDckI2NjN0UERFa2JrUk4yMW13",

"after": "QVFIUmlwbnFsM3N2cV9lZAFdCa0hDeV9qMVliT0VuMmJyNENxZA180c0t6VjFQVEJaTE9XV085aU92OUFLNFB6Szd2amo5aV9rTlVBcnNlWmEtMzYxcE1HSFR3"

}

If you are able to perform this final query successfully, you should be able to perform queries using any of the Instagram Graph API endpoints — just refer to our various guides and references to learn what each endpoint can do and what permissions they require.

如果您能够成功执行此最终查询，则应该能够使用任何Instagram Graph API端点执行查询-只需参考我们的各种指南和参考资料，以了解每个端点可以做什么以及它们需要什么权限。

Next Steps(下一步)

Develop your app further so it can successfully use any other endpoints it needs, and keep track of the permissions each endpoint requires
Complete the App Review process and request approval for all of the permissions your app will need so your app users can grant them while your app is in Live Mode
Switch your app to Live Mode and market it to potential users

Once your app is in Live Mode, any Facebook User who you've made your app available to can access an Instagram Business or Creator Account's data, as long as they have a Facebook User account that can perform Tasks on the Page connected to that Instagram Business or Creator Account.

进一步开发您的应用程序，使其可以成功使用所需的任何其他端点，并跟踪每个端点所需的权限
完成应用程序审核过程并请求批准您的应用程序所需的所有权限，以便您的应用程序用户可以在应用程序处于实时模式时为其授予权限
将您的应用切换到实时模式，并将其推销给潜在用户

您的应用进入实时模式后，只要您拥有可在连接到该Instagram的页面上执行任务的Facebook用户帐户，就可以使您的应用可用的任何Facebook用户都可以访问Instagram业务或创建者帐户的数据企业或创建者帐户。