Instagram API平台文档

原文链接： https://www.instagram.com/developer/

目录

Authentication(认证方式)

Do you need to authenticate?(您需要认证吗)

Receiving an access_token(接收一个access_token)

Server-side (Explicit) Flow(服务器端（显式）流程)

Step One: Direct your user to our authorization URL

第一步：将您的用户定向到我们的授权URL

Step Two: Receive the redirect from Instagram

第二步：从Instagram接收重定向

Step Three: Request the access_token

第三步：请求access_token

Client-Side (Implicit) Authentication(客户端（隐式）身份验证)

Step One: Direct your user to our authorization URL

第一步：将您的用户定向到我们的授权URL

Step Two: Receive the access_token via the URL fragment

第二步：通过URL片段接收access_token

Login Permissions (Scopes)登录权限（范围）

Valid use cases and associated scopes(有效的用例和相关范围)

Invalid use cases(无效的用例)

Permissions Review(权限审查)

How to Submit for Permissions Review

如何提交权限审查

Criteria for Review

审查标准

FAQ(常问问题)

Sandbox Mode(沙盒模式)

Sandbox Users(沙盒用户)

Login Permissions(登录权限)

API Behavior(API行为)

Going Live(上线)

Secure Requests(安全请求)

Disable Client-Side (Implicit) Authentication

禁用客户端（隐式）身份验证

Enforce Signed Requests

强制签署请求

重要

Signature format

签名格式

Examples

例子

Python

Ruby

PHP

Testing Signed Requests

测试签名的请求

API Endpoints(API端点)

Limits

限制

Deleting Objects

删除对象

Structure结构体

The Envelope信封

META元

DATA数据

PAGINATION分页

JSONP

---

 

Authentication(认证方式)

The Instagram API uses the OAuth 2.0 protocol for simple, but effective authentication and authorization. OAuth 2.0 is much easier to use than previous schemes and developers can start using the Instagram API almost immediately. The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://).

Instagram API使用OAuth 2.0协议进行简单但有效的身份验证和授权。OAuth 2.0比以前的方案更易于使用，开发人员几乎可以立即开始使用Instagram API。要记住的一件事是，所有对API的请求都必须通过SSL（http s：//而不是http：//）进行。

Do you need to authenticate?(您需要认证吗)

The Instagram API requires authentication - specifically requests made on behalf of a user. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future.

Instagram API需要身份验证-特别是代表用户的请求。经过身份验证的请求需要一个access_token。这些令牌对于用户是唯一的，应该安全地存储。访问令牌可能在将来的任何时候过期。

Receiving an access_token(接收一个access_token)

In order to receive an access_token, you must do the following:

1. Direct the user to our authorization url.

2. • If the user is not logged in, they will be asked to log in.

   • The user will be asked if they would like to grant your application access to her Instagram data.

3. The server will redirect the user in one of two ways that you choose:

4. • Server-side flow (recommended): Redirect the user to a URI of your choice. Take the provided codeparameter and exchange it for an access_token by POSTing the code to our access_token url.

   • Implicit flow: Instead of handling a code, we include the access_token as a fragment (#) in the URL. This method is less secure, but allows applications without any server component to receive an access_token.

为了接收access_token，您必须执行以下操作：

1. 将用户定向到我们的授权URL。

2. • 如果用户未登录，则将要求他们登录。

   • 系统将询问用户是否要授予您的应用程序对其Instagram数据的访问权限。

3. 服务器将以您选择的两种方式之一重定向用户：

4. • 服务器端流（推荐）：将用户重定向到您选择的URI。通过将代码发布到我们的access_token网址中，获取提供的code参数并将其交换为access_token。

   • 隐式流程：我们不处理代码，而是将access_token作为片段（＃）包含在URL中。此方法不太安全，但是允许没有任何服务器组件的应用程序接收access_token。

Important

Even though our access tokens do not specify an expiration time, your app should handle the case that either the user revokes access, or Instagram expires the token after some period of time. If the token is no longer valid, API responses will contain an “error_type=OAuthAccessTokenException”. In this case you will need to re-authenticate the user to obtain a new valid token.

In other words: do not assume your access_token is valid forever.

 

重要

即使我们的访问令牌未指定到期时间，您的应用也应处理以下情况：用户撤消访问权限，或者Instagram在一段时间后使令牌过期。如果令牌不再有效，则API响应将包含“ error_type = OAuthAccessTokenException”。在这种情况下，您将需要重新验证用户身份以获得新的有效令牌。

换句话说：不要假设您的access_token永远有效。

 

Server-side (Explicit) Flow(服务器端（显式）流程)

Using the server-side flow is quite easy. Simply follow these steps:

Step One: Direct your user to our authorization URL

https://api.instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=code

Note: You may provide an optional scope parameter to request additional permissions outside of the “basic” permissions scope. Learn more about scope.

Note: You may provide an optional state parameter to carry through a server-specific state. For example, you can use this to protect against CSRF issues.

At this point, we present the user with a login screen and then a confirmation screen where to grant your app access to her Instagram data.

使用服务器端流程非常容易。只需遵循以下步骤：

第一步：将您的用户定向到我们的授权URL

https://api.instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=code

 

注意：您可以提供一个可选的scope参数，以请求“基本”权限范围之外的其他权限。了解有关范围的更多信息。

注意：您可以提供一个可选的状态参数来传递服务器特定的状态。例如，您可以使用它来防止CSRF问题。

在这一点上，我们向用户显示一个登录屏幕，然后是一个确认屏幕，在此处向您的应用授予访问她的Instagram数据的权限。

Step Two: Receive the redirect from Instagram

Once a user authorizes your application, we issue a redirect to your redirect_uri with a code parameter to use in step three.

http://your-redirect-uri?code=CODE

Note that the host and path components of your redirect URI must match exactly (including trailing slashes) your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically. Examples:

REGISTERED REDIRECT URI	REDIRECT_URI PARAMETER PASSED TO /AUTHORIZE	VALID?
http://yourcallback.com/	http://yourcallback.com/	yes
http://yourcallback.com/	http://yourcallback.com/?this=that	yes
http://yourcallback.com/?this=that	http://yourcallback.com/	no
http://yourcallback.com/?this=that	http://yourcallback.com/?this=that&another=true	yes
http://yourcallback.com/?this=that	http://yourcallback.com/?another=true&this=that	no
http://yourcallback.com/callback	http://yourcallback.com/	no
http://yourcallback.com/callback	http://yourcallback.com/callback?type=mobile	yes

If your request for approval is denied by the user, then we will redirect the user to your redirect_uri with the following parameters:

• error: access_denied

• error_reason: user_denied

• error_description: The user denied your request

  http://your-redirect-uri?error=access_denied&error_reason=user_denied&error_description=The+user+denied+your+request

   

It is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.

第二步：从Instagram接收重定向

一旦用户授权了您的应用程序，我们就会在第三步中使用代码参数向您的redirect_uri发出重定向。

http://your-redirect-uri?code=CODE

请注意，您的重定向URI的主机和路径组件必须与您注册的redirect_uri完全匹配（包括斜杠）。如果需要动态更改行为，还可以在提供的redirect_uri中包括其他查询参数。例子：

注册重定向URI	传递给/ AUTHORIZE的REDIRECT_URI参数	有效？
http://yourcallback.com/	http://yourcallback.com/	是
http://yourcallback.com/	http://yourcallback.com/?this=that	是
http://yourcallback.com/?this=that	http://yourcallback.com/	没有
http://yourcallback.com/?this=that	http://yourcallback.com/?this=that&another=true	是
http://yourcallback.com/?this=that	http://yourcallback.com/?another=true&this=that	没有
http://yourcallback.com/callback	http://yourcallback.com/	没有
http://yourcallback.com/callback	http://yourcallback.com/callback?type=mobile	是

如果用户拒绝了您的批准请求，那么我们将使用以下参数将用户重定向到您的redirect_uri：

• 错误：access_denied

• error_reason：user_denied

• error_description：用户拒绝了您的请求

  http://your-redirect-uri?error=access_denied&error_reason=user_denied&error_description=The+user+denied+your+request

   

   

您有责任在这种情况下正常失败并向用户显示相应的错误消息。

 

Step Three: Request the access_token

Now you need to exchange the code you have received in the previous step for an access token. In order to make this exchange, you simply have to POST this code, along with some app identification parameters, to our access_token endpoint. These are the required parameters:

• client_id: your client id

• client_secret: your client secret

• grant_type: authorization_code is currently the only supported value

• redirect_uri: the redirect_uri you used in the authorization request. Note: this has to be the same value as in the authorization request.

• code: the exact code you received during the authorization step.

This is a sample request:

 

    curl -F 'client_id=CLIENT_ID' \

    -F 'client_secret=CLIENT_SECRET' \

    -F 'grant_type=authorization_code' \

    -F 'redirect_uri=AUTHORIZATION_REDIRECT_URI' \

    -F 'code=CODE' \

    https://api.instagram.com/oauth/access_token

If successful, this call will return a neatly packaged OAuth Token that you can use to make authenticated calls to the API. We also include the user who just authenticated for your convenience:

{

    "access_token": "fb2e77d.47a0479900504cb3ab4a1f626d174d2d",

    "user": {

        "id": "1574083",

        "username": "snoopdogg",

        "full_name": "Snoop Dogg",

        "profile_picture": "..."

    }

}

 

第三步：请求access_token

现在，您需要将在上一步中收到的代码交换为访问令牌。为了进行此交换，您只需要将此代码以及一些应用程序标识参数发布到我们的access_token端点即可。这些是必需的参数：

• client_id：您的客户ID

• client_secret：您的客户机密

• grant_type：authorization_code是当前唯一受支持的值

• redirect_uri：您在授权请求中使用的redirect_uri。注意：此值必须与授权请求中的值相同。

• code：您在授权步骤中收到的确切代码。

这是一个示例请求：

 

    curl -F 'client_id=CLIENT_ID' \

    -F 'client_secret=CLIENT_SECRET' \

    -F 'grant_type=authorization_code' \

    -F 'redirect_uri=AUTHORIZATION_REDIRECT_URI' \

    -F 'code=CODE' \

    https://api.instagram.com/oauth/access_token

如果成功，此调用将返回一个整齐打包的OAuth令牌，可用于对API进行经过身份验证的调用。为了方便您，我们还包括刚刚通过身份验证的用户：

{

    "access_token": "fb2e77d.47a0479900504cb3ab4a1f626d174d2d",

    "user": {

        "id": "1574083",

        "username": "snoopdogg",

        "full_name": "Snoop Dogg",

        "profile_picture": "..."

    }

}

 

Client-Side (Implicit) Authentication(客户端（隐式）身份验证)

 

If you are building an app that does not have a server component (a purely javascript app, for instance), you will notice that it is impossible to complete step three above to receive your access_token without also having to store the secret on the client. You should never pass or store your client_id secret onto a client. For these situations there is the Implicit Authentication Flow.

如果您要构建的应用程序不具有服务器组件（例如，纯JavaScript应用程序），您会注意到，无法完成上述第三步来接收access_token，而不必在客户端上存储密码。您绝不应将client_id机密传递或存储到客户端上。对于这些情况，存在隐式身份验证流程。

Step One: Direct your user to our authorization URL

https://api.instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token

At this point, we present the user with a login screen and then a confirmation screen where they grant your app’s access to their Instagram data. Note that unlike the explicit flow the response type here is “token”.

第一步：将您的用户定向到我们的授权URL

https://api.instagram.com/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token

在这一点上，我们向用户显示一个登录屏幕，然后是一个确认屏幕，在该屏幕上，他们向您的应用授予访问其Instagram数据的权限。请注意，与显式流程不同，此处的响应类型为“令牌”。

Step Two: Receive the access_token via the URL fragment

Once the user has authenticated and then authorized your application, Instagram redirects them to your redirect_uri with the access_token in the url fragment. It will look like this:

http://your-redirect-uri#access_token=ACCESS-TOKEN

Simply grab the access_token off the URL fragment and you’re good to go. If the user chooses not to authorize your application, you’ll receive the same error response as in the explicit flow

第二步：通过URL片段接收access_token

一旦用户通过身份验证并授权了您的应用程序，Instagram就会使用url片段中的access_token将其重定向到您的redirect_uri。它看起来像这样：

http://your-redirect-uri#access_token=ACCESS-TOKEN

只需从URL片段中获取access_token，就可以了。如果用户选择不授权您的应用程序，您将收到与显式流程相同的错误响应

 

Login Permissions (Scopes)登录权限（范围）

The OAuth 2.0 specification allows you to specify the scope of the access you are requesting from the user. All approved apps have basic access by default, but if you plan on asking for extended access such as reading public content, liking, commenting, or managing friendships, you will need to specify these scopes in your authorization request. Note that in order to use these extended permissions, you must first submit your app for review. Here are the scopes we currently support:

OAuth 2.0规范允许您指定要向用户请求的访问范围。默认情况下，所有已批准的应用程序都具有基本访问权限，但是如果您打算要求扩展访问权限，例如阅读公共内容，喜欢，发表评论或管理友谊，则需要在授权请求中指定这些范围。请注意，为了使用这些扩展权限，您必须首先将您的应用程序提交以进行审查。以下是我们目前支持的范围：

• basic - to read a user’s profile info and media

• 基本 -读取用户的个人资料信息和媒体

Valid use cases and associated scopes(有效的用例和相关范围)

While in sandbox, your app has access to all permissions and you can generate access tokens with any scope for testing. To use these scopes in production though, your app needs to go through review and be approved for a given permission. The permissions your app can be approved for relate directly to the use case of your app.

You should only request the permissions that map to your use case:

在沙盒中时，您的应用有权访问所有权限，并且可以生成具有任何测试范围的访问令牌。要在生产环境中使用这些范围，您的应用需要经过审查并获得给定的许可。可以批准您的应用程序的权限直接与您的应用程序用例相关。

您只应请求映射到您的用例的权限：

To help individuals share their own content with 3rd party apps: basic

This use case is meant for apps that allow the general public to login with Instagram to get their own content; for example, an app that allows people to print their own pictures. Apps that fall into this use case will only have access to the basic permission.

为了帮助个人与第三方应用共享他们自己的内容： 基本

此用例适用于允许普通公众通过Instagram登录以获取自己的内容的应用；例如，允许人们打印自己的照片的应用程序。属于此用例的应用将只能访问基本权限。

 

Invalid use cases(无效的用例)

Here are some examples of use cases that we do not support:

以下是一些我们不支持的用例示例：

Widget Installs. If you are installing a widget for your website, then you do not need to submit for permissions review. If you are installing a widget for your website, then you do not need to submit for review. Some widgets may ask you to create a new client id, but you do not need to submit it for review for the widget to work. Your client can remain in sandbox mode and the widget will have access to your last 20 media.

小部件安装。如果您正在为网站安装窗口小部件，则无需提交权限审查。如果您要为网站安装窗口小部件，则无需提交进行审查。某些小部件可能会要求您创建一个新的客户端ID，但是您无需将其提交以供审核即可使用。您的客户端可以保持沙盒模式，该小部件可以访问您最近的20种媒体。

One-off Projects. If you are an agency building websites or other integrations, note that we don't grant permissions to clients created for one-off projects. If you are interested in building a product, platform, or widget that will be used as a service across multiple projects, then you may submit a single client_id that you can use across multiple projects.

一次性项目。如果您是建立网站或其他集成的代理商，请注意，我们不会向为一次性项目创建的客户授予权限。如果您有兴趣构建可在多个项目中用作服务的产品，平台或小部件，则可以提交可在多个项目中使用的单个client_id。

Content Display for Personal Website. If you are a developer and you want to showcase Instagram content on a website, then you do not need to submit your app for review. By using a client in sandbox mode, you will still be able to access the last 20 media of any sandbox user that grants you permission.

个人网站的内容显示。如果您是开发人员，并且想在网站上展示Instagram内容，则无需提交您的应用程序以供审核。通过在沙盒模式下使用客户端，您仍将能够访问任何授予您权限的沙盒用户的最后20个媒体。

Permissions Review(权限审查)

Every new app created on the Instagram Platform starts in Sandbox mode. Apps in this mode can use any API endpoint but are restricted to a limited number of users and media. This is great for developing and testing your app.

To go Live and fully access Instagram content, you will need to submit your application for review and approval. Once reviewed, you will only be able to request users the Permission Scopes for which your app was approved. Because of this, your application may not be able to use some API endpoints unless the corresponding permissions were reviewed and approved.

The review process allows us to ensure an authentic and consistent experience for the Instagram Community. The app review process aims to help community members more granularly control how their content is being shared through 3rd party apps and that those apps are building compliant use cases.

在Instagram平台上创建的每个新应用都以沙盒模式启动。此模式下的应用程序可以使用任何API终结点，但仅限于有限数量的用户和媒体。这对于开发和测试您的应用程序非常有用。

要上线并完全访问Instagram内容，您需要提交您的应用程序以供审核和批准。审核后，您将只能向用户请求批准您的应用的权限范围。因此，您的应用程序可能无法使用某些API终结点，除非经过相应的权限审查和批准。

审核过程使我们能够确保对Instagram社区的真实和一致的体验。应用程序审核过程旨在帮助社区成员更精细地控制如何通过第三方应用程序共享其内容以及这些应用程序正在构建兼容的用例。

How to Submit for Permissions Review

• Go to Manage Clients and edit the app you want to submit for review

• In the Details tab make sure to fill out all fields and save any change with the Update Client button

• Go to the Permissions tab which shows each permission and their review status

• Click the Start a submission button and then follow the instructions

The result of your submission will appear in the same Permissions tab. Note that you will not be able to submit again until we have reviewed your submission.

如何提交权限审查

• 转到“ 管理客户”并编辑您要提交以供审核的应用

• 在Details标签中，确保填写所有字段并使用Update Client按钮保存所有更改

• 转到Permissions显示每个权限及其查看状态的标签

• 单击Start a submission按钮，然后按照说明进行操作

提交的结果将显示在同一Permissions选项卡中。请注意，在我们审核您的提交内容之前，您将无法再次提交。

Criteria for Review

Submission quality: Notes must be clear, concise and in English. We will not approve submissions with insufficient notes.

Video screencast quality: The video screencast must show the Instagram login experience of your app, proper credentials and the usage of every permission you are requesting. We will not approve submissions if you do not provide a clear and working screencast.

App development phase: We only review final and production version apps. Submissions with test and development version apps will not be approved.

Brand and policy compliance: Your app must comply with Instagram Platform Policy and Instagram Brand Guidelines.

Use case and permissions compliance:

We will approve submissions of apps that fall into these use case:

• To help individuals share their own content with 3rd party apps

For more information on the use cases we support, please read the Login Permission documentation.

审查标准

提交质量：注释必须清晰，简明且使用英语。我们不会批准注释不足的提交。

视频截屏质量：视频截屏质量必须显示您的应用程序的Instagram登录体验，正确的凭据以及所请求的每个权限的使用。如果您没有提供清晰有效的截屏视频，我们将不批准提交。

应用开发阶段：我们仅审查最终版和正式版应用。使用测试和开发版本应用程序提交的内容将不获批准。

品牌和政策合规性：您的应用程序必须符合Instagram平台政策和Instagram品牌准则。

用例和权限合规性：

我们将批准属于以下用例的应用程序提交：

• 帮助个人与第三方应用共享他们自己的内容

有关我们支持的用例的更多信息，请阅读“ 登录许可”文档。

FAQ(常问问题)

My submission was rejected but it was a valid use case. What should I do? A common reason for rejecting a submission is that we do not have enough information to make an assessment of your app. This can happen if your submission was too short, if it missed important information, if you did not provide a good screencast, your website is not working, etc. Before you submit for review again, make sure to provide a long and clear explanation of what your app does and how you use every permission. Make sure also to provide a video screencast and to follow all our Platform Policies.

我的提交被拒绝了，但这是一个有效的用例。我该怎么办？拒绝提交的常见原因是我们没有足够的信息来评估您的应用。如果您提交的内容太短，错过了重要信息，如果您没有提供良好的截屏视频，您的网站无法正常工作等，可能会发生这种情况。在再次提交审阅之前，请确保提供以下内容的清晰明确的说明：您的应用程序做什么以及如何使用每个权限。确保还提供视频截屏并遵守我们的所有平台政策。

What should I write in the submission? The submission should be long enough for us to understand exactly what your app does and why you need the permissions you are asking for. If your submission is too short or does not explain all parts of your integration, then we may not be able to understand and approve your app. For example, your submission should explain what does your app or company do, which of the approved use cases your integration falls into, who will be using your app, how do your user authenticate with your app, how you use the API to power your integration, how does your product use the data acquired from Instagram, etc.

我应该在提交的内容中写些什么？提交的时间应足够长，以使我们能够准确了解您的应用程序的功能以及为什么需要您所要求的权限。如果您提交的内容太短或无法解释集成的所有部分，则我们可能无法理解和批准您的应用。例如，您的提交内容应说明您的应用程序或公司做什么，集成属于哪些批准的用例，谁将使用您的应用程序，用户如何通过您的应用程序进行身份验证，如何使用API来驱动您的应用程序集成，您的产品如何使用从Instagram获取的数据等。

What should I show in the video screencast? The video screencast is a very important part of a submission and cannot be omitted. Please make sure that the video clearly shows how your application works, including any Instagram login experience and the usage of every permission you are requesting. Since your app may still be in sandbox mode, you can use data from sandbox users to showcase the integration.

我应该在视频截屏中显示什么？视频截屏视频是提交内容中非常重要的一部分，不能忽略。请确保视频清楚地显示您的应用程序的工作方式，包括任何Instagram登录体验以及您所请求的每个权限的使用。由于您的应用可能仍处于沙盒模式，因此您可以使用沙盒用户的数据来展示集成。

My company is working with multiple clients, should I submit one app per project? No, we do not approve apps that are created for one-off projects (e.g. a hashtag campaign, an event, a website). You should use a single client_id across all your integrations.

我的公司与多个客户合作，我应该为每个项目提交一个应用程序吗？不，我们不批准为一次性项目创建的应用（例如，主题标签活动，活动，网站）。您应该client_id在所有集成中使用一个。

Can I revoke a submission if I made a mistake? You can't cancel a submission that is in progress. You will need to wait until the submission has been reviewed before you can start a new one. 

如果输入有误，我可以撤消提交内容吗？您无法取消正在进行的提交。您将需要等到提交被审核后，才能开始新的提交。

Sandbox Mode(沙盒模式)

Every new app created on the Instagram Platform starts in Sandbox mode. This is a fully functional environment that allows you to test the API before submitting your app for review. Sandbox mode is ideal for developers who are new to the Instagram Platform and want to explore the API Platform, as well as for teams that need multiple clients for development, staging, and other non-live environments.

在Instagram平台上创建的每个新应用都以沙盒模式启动。这是一个功能齐全的环境，可让您在将应用提交审核之前测试API。沙箱模式非常适合刚接触Instagram平台并希望探索API平台的开发人员，以及需要多个客户端进行开发，登台和其他非实时环境的团队。

To help you develop and test your app, the users and media available in Sandbox mode are real Instagram data (i.e. what is normally visible in the Instagram app), but with the following conditions:

• Apps in sandbox are restricted to 10 users

• Data is restricted to the 10 users and the 20 most recent media from each of those users

• Reduced API rate limits

为了帮助您开发和测试您的应用，沙盒模式下可用的用户和媒体是真实的Instagram数据（即通常在Instagram应用中可见的数据），但具有以下条件：

• 沙盒中的应用程序仅限10个用户

• 数据仅限于10个用户以及每个用户的20个最新媒体

• 降低API 速率限制

The next section will explain these conditions in more detail and how you can leverage Sandbox mode to build and test your app. Only apps that are reviewed and approved will be able to get out of Sandbox mode and be available to any Instagram user.

下一节将更详细地说明这些条件，以及如何利用沙盒模式来构建和测试您的应用程序。只有经过审核和批准的应用程序才能退出沙盒模式，并且对任何Instagram用户都可用。

Sandbox Users(沙盒用户)

When you want to start working with the Instagram API Platform, you can register a new app that will start in Sandbox mode. Since this mode is meant for development, apps in Sandbox mode are not visible to the general public, but instead are only visible to a limited set of up to 10 authorized 'sandbox users'. Only these users will be able to test and authenticate your app.

当您想开始使用Instagram API平台时，可以注册一个将在沙盒模式下启动的新应用。由于此模式用于开发，因此沙盒模式下的应用程序对公众不可见，而仅对最多10个授权“沙盒用户”的有限集合可见。只有这些用户才能测试和验证您的应用。

To manage the list of sandbox users for a given app, you can go to the Sandbox tab in your client configuration screen. There you will be able to add and remove the sandbox users for your app, up to a maximum of 10 users. Note that the admin of the app is always a sandbox user, so you can effectively add up to 9 additional 'sandbox users’.

要管理给定应用程序的沙箱用户列表，可以转到客户端配置屏幕中的“沙箱”选项卡。您可以在其中添加和删除应用程序的沙箱用户，最多10个用户。请注意，应用程序的管理员始终是沙盒用户，因此您可以有效地添加多达9个其他“沙盒用户”。

After adding users to the list, they will have to accept your invitation before actually becoming sandbox users. To accept the invitation, they can go to the 'Sandbox Invites' button on the top bar of the developer site. In the 'Sandbox Invites' page people can accept or reject invitations, and also stop being sandbox users for a given app.

将用户添加到列表后，他们必须先接受您的邀请，然后才能真正成为沙盒用户。要接受邀请，他们可以转到开发者网站顶部栏上的“沙盒邀请”按钮。在“沙箱邀请”页面中，人们可以接受或拒绝邀请，也可以停止成为给定应用程序的沙箱用户。

Note: a user can become a sandbox user of up to 5 apps. You will not be able to invite someone that is already a test user of 5 apps.

注意：一个用户最多可以成为5个应用的沙盒用户。您将无法邀请已经是5个应用程序测试用户的人。

Login Permissions(登录权限)

Now that you have some sandbox users, you can have them go through the authorization flow and generate an access token. The OAuth dialog will display a warning that the app being authorized is in sandbox mode, which is a good reminder that the OAuth dialog will work only for sandbox users. If anyone else tries to authorize your sandbox app, they will see a OAuthForbiddenException error message.

现在您有了一些沙箱用户，您可以让他们遍历授权流程并生成访问令牌。OAuth对话框将显示警告，表明正在授权的应用程序处于沙盒模式，这很好地提醒了OAuth对话框仅对沙盒用户有效。如果其他任何人试图授权您的沙盒应用程序，他们将看到OAuthForbiddenException错误消息。

Apps in sandbox can use any of the login permissions available. This will allow you to generate access tokens that have any of the scopes required to test the behavior of the API endpoints. While this is great for testing, remember that you still have to go through the permission review process if you want to be granted the ability to use the permissions when you go live.

沙箱中的应用程序可以使用任何可用的登录权限。这将使您能够生成具有测试API端点行为所需的任何范围的访问令牌。虽然这非常适合测试，但是请记住，如果要在上线时被授予使用权限的能力，则仍必须经过权限检查过程。

API Behavior(API行为)

The behavior of the API when you are in sandbox mode is the same as when your app is live, but comes with the following restrictions:

• Data is restricted to sandbox users and the 20 most recent media from each sandbox user

• Reduced API rate limits

处于沙盒模式时，API的行为与应用程序处于活动状态时的行为相同，但具有以下限制：

• 数据仅限沙盒用户和每个沙盒用户的20种最新媒体

• 降低API 速率限制

The first point is important and it means that the API behaves as if the only users on Instagram were your sandbox users, and the only media ever posted were the last 20 for each of these users.

For example, if you query the /users/{user-id}/ endpoint and the {user-id} is a sandbox user, then you will get the normal API response; but if the {user-id} is not a sandbox user, you will get a APINotFound error.

As another example, let's consider an endpoint that returns a list of media: /tags/{tag-name}/media/recent. The response returned by this endpoint will contain only media with the given tag, as expected. But instead of returning media from any public Instagram user, it will return only media that belongs to your sandbox users, restricted to the last 20 for each user.

第一点很重要，它意味着API的行为就像Instagram上唯一的用户是您的沙箱用户，而发布过的唯一媒体是这些用户中每一个的最后20个。

例如，如果您查询/users/{user-id}/端点，并且{user-id}是沙箱用户，那么您将获得正常的API响应；但是如果{user-id}并非沙盒用户，则会收到APINotFound错误消息。

再举一个例子，让我们考虑一个返回媒体列表的终结点：/tags/{tag-name}/media/recent。如预期的那样，此端点返回的响应将仅包含具有给定标签的媒体。但是，它不会返回任何公共Instagram用户的媒体，而只会返回属于您的沙箱用户的媒体，每个用户的媒体限制为最后20个。

Going Live(上线)

To get out of Sandbox mode, you need to submit your app for review. If your app falls into the approved use cases and gets approved, it will automatically go live. At this point any Instagram user will be able to authorize your app, but you will have access only to the permissions that you were granted during the review. If you need access to more permissions, you can submit for review again and you will not lose access to the permissions that you have already been granted.

要退出沙盒模式，您需要提交您的应用以供审核。如果您的应用属于批准的用例并获得批准，它将自动上线。此时，任何Instagram用户都可以对您的应用进行授权，但是您将只能访问审阅期间授予的权限。如果需要访问更多权限，则可以再次提交以供审阅，并且不会失去对已被授予的权限的访问权限。

Secure Requests(安全请求)

Most API calls require an access token, but malicious developers can impersonate OAuth Clients or steal access tokens. They will then use these to send spam on the behalf of your app. Instagram has automated systems to detect spam, and will automatically disable the OAuth Clients responsible for these calls. You can mitigate the risk of your app being disabled by restricting some vectors of abuses. This document covers some of the ways you can protect your app.

大多数API调用都需要访问令牌，但是恶意开发人员可以模拟OAuth客户端或窃取访问令牌。然后，他们将使用它们代表您的应用发送垃圾邮件。Instagram具有自动检测垃圾邮件的系统，并将自动禁用负责这些呼叫的OAuth客户端。您可以通过限制某些滥用行为来减轻应用程序被禁用的风险。本文档介绍了一些保护应用程序的方法。

Disable Client-Side (Implicit) Authentication

The Implicit OAuth Grant flow was created for java-script or mobile clients. Many developers use this flow because of its convenience. Unfortunately, malicious developers can also use this flow to trick people into authorizing your OAuth Client. They can collect access tokens and then make API calls on behalf of your app. When this occurs, your OAuth Client could be banned from the platform by our spam detection systems.

If your app is powered by a server infrastructure, you can disable the Client-Side (Implicit) OAuth flow by checking the Disable implicit OAuth setting in your OAuth Client configuration. If checked, Instagram will reject Client-Side (Implicit) authorization requests and only grant Server-Side (Explicit) authorization requests. This setting helps protect your app because the Server-Side (Explicit) OAuth flow requires the use of your Client Secret, which should be unknown to malicious developers.

禁用客户端（隐式）身份验证

该隐的OAuth格兰特流是为Java的脚本或移动客户端创建。由于其便利性，许多开发人员都使用此流程。不幸的是，恶意开发人员也可以使用此流程诱使人们授权您的OAuth客户端。他们可以收集访问令牌，然后代表您的应用程序进行API调用。发生这种情况时，我们的垃圾邮件检测系统可能会从平台禁止您的OAuth客户端。

如果您的应用由服务器基础架构提供支持，则可以通过选中OAuth客户端配置中的禁用隐式OAuth设置来禁用客户端（隐式）OAuth流。如果选中，Instagram将拒绝客户端（隐式）授权请求，并且仅授予服务器端（显式）授权请求。此设置有助于保护您的应用程序，因为服务器端（显式）OAuth流程需要使用您的客户端密钥，恶意开发人员不应该知道。

Important

Your Client Secret should be kept secure at all times. Do not share this Secret with anyone, do not include it in java-script code or a mobile client. Mobile apps that do not have a server-side component should have the Disable implicit OAuth setting unchecked. You have the ability to reset your Client Secret to a new value at any time, if you suspect that it was leaked.

 

重要

您的客户机密应始终保持安全。请勿与任何人共享此秘密，请勿将其包含在Java脚本代码或移动客户端中。没有服务器端组件的移动应用程序应取消选中“ 禁用隐式OAuth”设置。如果您怀疑客户端机密已泄漏，可以随时将其重置为新值。

 

Enforce Signed Requests

Access tokens are portable: they can be generated on one machine and re-used elsewhere. Access tokens can also be stolen by malicious software on a person's computer or a man in the middle attack. A stolen access token can then be used to generate spam. When targeted by such abuses, your app could be blocked by our automated systems.

You can secure your API calls and mitigate impersonation attempts by making server-side calls and passing a per-request signature using your Client Secret. Edit your OAuth Client configuration and mark the Enforce signed requests checkbox. When enabled, Instagram will check for the sig parameter of each request and verify that the value matches a hash computed using your Client Secret. The expected value is a HMAC using the SHA256 hash algorithm with all your request parameters and your Client Secret.

强制签署请求

访问令牌是可移植的：它们可以在一台计算机上生成并在其他计算机上重复使用。访问令牌也可能被攻击者或他人的计算机上的恶意软件窃取。然后，可以使用被盗的访问令牌来生成垃圾邮件。当此类滥用成为目标时，您的应用可能会被我们的自动化系统阻止。

您可以通过进行服务器端调用并使用客户端密钥传递每个请求的签名来保护API调用并减轻模拟尝试。编辑您的OAuth客户端配置，然后选中执行已签名的请求复选框。启用后，Instagram将检查每个请求的sig参数，并验证该值是否匹配使用“客户端密钥”计算出的哈希值。期望值为使用SHA256哈希算法以及所有请求参数和客户端密码的HMAC。

Important

Your Client Secret should be kept secure at all times. Do not share this Secret with anyone, do not include it in java-script code or a mobile client. Mobile apps that do not have a server-side component should not use the Enforce signed requests setting. You have the ability to reset your Client Secret to a new value at any time, if you suspect that it was leaked.

 

重要

您的客户机密应始终保持安全。请勿与任何人共享此秘密，请勿将其包含在Java脚本代码或移动客户端中。没有服务器端组件的移动应用程序不应使用“ 强制签名请求”设置。如果您怀疑客户端机密已泄漏，可以随时将其重置为新值。

Signature format

Token to sign: endpoint|key1=value1|key2=value2|...

 

Parameter name: sig

Parameter value: signed token with your Client Secret using the SHA256 hash algorithm

• Token: API endpoint appended with a concatenation of all key/value pairs of your request parameters, sorted by key in ascending order. Each key/value pair is separated by the pipe character.

 

签名格式

Token to sign: endpoint|key1=value1|key2=value2|...

 

Parameter name: sig

Parameter value: signed token with your Client Secret using the SHA256 hash algorithm

• 令牌：API端点附加了您的请求参数的所有键/值对的串联，并按键升序排序。每个键/值对由竖线字符分隔。

Examples

Endpoint: /users/self Parameters: access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d App Secret: 6dc1787668c64c939929c17683d7cb74

With this example, the signature key/value should be:

sig=cbf5a1f41db44412506cb6563a3218b50f45a710c7a8a65a3e9b18315bb338bf

Endpoint: /media/657988443280050001_25025320 Parameters: access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&count=10 App Secret: 6dc1787668c64c939929c17683d7cb74

Here the signature key/value would then be:

sig=260634b241a6cfef5e4644c205fb30246ff637591142781b86e2075faf1b163a

The signature describes the hex representation of a RFC 2104-compliant HMAC with the SHA256 hash algorithm, using the API endpoint, your request parameters and your Client Secret. Most programming languages provide the tools to create such a signature. Here are some examples to get you started.

 

例子

端点：/用户/自我参数：access_token = fb2e77d.47a0479900504cb3ab4a1f626d174d2d应用程序密钥：6dc1787668c64c939929c17683d7cb74

在此示例中，签名密钥/值应为：

sig=cbf5a1f41db44412506cb6563a3218b50f45a710c7a8a65a3e9b18315bb338bf

端点：/ media / 657988443280050001_25025320参数：access_token = fb2e77d.47a0479900504cb3ab4a1f626d174d2d＆count = 10应用程序机密：6dc1787668c64c939929c17683d7cb74

签名密钥/值将为：

sig=260634b241a6cfef5e4644c205fb30246ff637591142781b86e2075faf1b163a

该签名使用API端点，您的请求参数和您的客户机密，使用SHA256哈希算法描述了符合RFC 2104的HMAC的十六进制表示形式。大多数编程语言都提供创建此类签名的工具。以下是一些示例，可帮助您入门。

Python

# -*- coding: UTF-8 -*-

import hmac

from hashlib import sha256



def generate_sig(endpoint, params, secret):

    sig = endpoint

    for key in sorted(params.keys()):

        sig += '|%s=%s' % (key, params[key])

    return hmac.new(secret, sig, sha256).hexdigest()



endpoint = '/media/657988443280050001_25025320'

params = {

    'access_token': 'fb2e77d.47a0479900504cb3ab4a1f626d174d2d',

    'count': 10,

}

secret = '6dc1787668c64c939929c17683d7cb74'



sig = generate_sig(endpoint, params, secret)

print sig

Ruby

require 'openssl'

require 'base64'



def generate_sig(endpoint, params, secret)

  sig = endpoint

  params.sort.map do |key, val|

    sig += '|%s=%s' % [key, val]

  end

  digest = OpenSSL::Digest::Digest.new('sha256')

  return OpenSSL::HMAC.hexdigest(digest, secret, sig)

end



endpoint = '/media/657988443280050001_25025320'

params = {

  'access_token' => 'fb2e77d.47a0479900504cb3ab4a1f626d174d2d',

  'count' => 10,

}

secret = '6dc1787668c64c939929c17683d7cb74'



sig = generate_sig(endpoint, params, secret)

print sig

PHP

 $val) {

    $sig .= "|$key=$val";

  }

  return hash_hmac('sha256', $sig, $secret, false);

}



$endpoint = '/media/657988443280050001_25025320';

$params = array(

  'access_token' => 'fb2e77d.47a0479900504cb3ab4a1f626d174d2d',

  'count' => 10,

);

$secret = '6dc1787668c64c939929c17683d7cb74';



$sig = generate_sig($endpoint, $params, $secret);

echo $sig;

Testing Signed Requests

Using an invalid signature will cause your API calls to fail if the Enforce signed requests setting is set. Because of this, you may want to test this parameter before you enable the setting for production code. Fortunately you can use cURL to test your header format and signature easily:

测试签名的请求

如果设置了“ 强制签名请求”设置，则使用无效签名将导致您的API调用失败。因此，在启用生产代码设置之前，您可能需要测试此参数。幸运的是，您可以使用cURL轻松测试标头格式和签名：

curl \

  -X POST \

  -F 'access_token=' \

  -F 'sig=' \

  https://api.instagram.com/v1/media/657988443280050001_25025320/likes

 

Common responses:（常见回应）

REASON	RESPONSE
Success	{"meta":{"code":200},"data":null}
Signature is required	{"code": 403, "error_type": "OAuthForbiddenException", "error_message": "Missing required parameter 'sig'"}
Failed to validate signature	{"code": 403, "error_type": "OAuthForbiddenException", "error_message": "Signature does not match"}

API Endpoints(API端点)

Once you've registered your client it's easy to start requesting data from Instagram.

All endpoints are only accessible via https and are located at api.instagram.com. For instance: you can retrieve photos with a given hashtag by accessing the following URL with your access_token (replace ACCESS-TOKEN with your own):

https://api.instagram.com/v1/self/media/recent?access_token=ACCESS_TOKEN

The Instagram API requires an access_token from authenticated users for each endpoint. We no longer support making requests using just the client_id.

一旦注册了客户，就可以轻松地从Instagram请求数据。

所有端点只能通过https访问，并且位于api.instagram.com。例如：您可以使用以下网址访问带有给定主题标签的照片access_token（将ACCESS-TOKEN替换为您自己的）：

https://api.instagram.com/v1/self/media/recent?access_token=ACCESS_TOKEN

Instagram API要求access_token每个端点都有来自经过身份验证的用户。我们不再支持仅使用发出请求client_id。

 

Note

The URL examples throughout this documentation use ACCESS-TOKEN as a placeholder. For these examples to work, you need to substitute the value with your own access_token. In your application, you should have each user go through an authentication and authorization flow in order to receive a valid access_token.

 

注意

本文档中的URL示例使用ACCESS-TOKEN作为占位符。为了使这些示例生效，您需要用自己的替换值access_token。在您的应用程序中，您应该让每个用户都经过身份验证和授权流程才能接收到有效的access_token。

Limits

Please refer to the limits documentation for information on rate limits that apply to API requests.

 

限制

请参阅限制文档，以了解适用于API请求的速率限制信息。

Deleting Objects

We do our best to have all our URLs be RESTful. Every endpoint (URL) may support one of four different http verbs. GET requests fetch information about an object, POST requests create objects, PUT requests update objects, and finally DELETE requests will delete objects.

删除对象

我们尽力使所有URL都是RESTful的。每个端点（URL）都可以支持四个不同的http动词之一。GET请求获取有关对象的信息，POST请求创建对象，PUT请求更新对象，最后DELETE请求将删除对象。

Structure结构体

The Envelope信封

Every response is contained by an envelope. That is, each response has a predictable set of keys with which you can expect to interact:

每个响应都包含在信封中。也就是说，每个响应都有一组可预测的键，您可以期望与它们进行交互：

{

    "meta": {

        "code": 200

    },

    "data": {

        ...

    },

    "pagination": {

        "next_url": "...",

        "next_max_id": "13872296"

    }

}

META元

The meta key is used to communicate extra information about the response to the developer. If all goes well, you'll only ever see a code key with value 200. However, sometimes things go wrong, and in that case you might see a response like:

元密钥用于将有关响应的额外信息传达给开发人员。如果一切顺利，您将只会看到一个值为200的代码键。但是，有时会出错，在这种情况下，您可能会看到类似以下的响应：

{

    "meta": {

        "error_type": "OAuthException",

        "code": 400,

        "error_message": "..."

    }

}

DATA数据

The data key is the meat of the response. It may be a list or dictionary, but either way this is where you'll find the data you requested.

数据键是响应的关键。它可能是列表或字典，但是无论哪种方式，您都可以在其中找到所需的数据。

PAGINATION分页

Sometimes you just can't get enough. For this reason, we've provided a convenient way to access more data in any request for sequential data. Simply call the url in the next_url parameter and we'll respond with the next set of data.

有时，您只是受不了。因此，我们提供了一种方便的方式来访问任何对顺序数据的请求中的更多数据。只需在next_url参数中调用url，我们将用下一组数据进行响应。

{

    ...

    "pagination": {

        "next_url": "https://api.instagram.com/v1/self/media/recent?access_token=fb2e77d.47a0479900504cb3ab4a1f626d174d2d&max_id=13872296",

        "next_max_id": "13872296"

    }

}

On views where pagination is present, we also support the "count" parameter. Simply set this to the number of items you'd like to receive. Note that the default values should be fine for most applications - but if you decide to increase this number there is a maximum value defined on each endpoint.

在存在分页的视图上，我们还支持“计数”参数。只需将其设置为您要接收的项目数即可。请注意，对于大多数应用程序，默认值应该很好-但是，如果您决定增加此数字，则每个端点上都会定义一个最大值。

JSONP

If you're writing an AJAX application, and you'd like to wrap our response with a callback, all you have to do is specify a callback parameter with any API call:

如果您正在编写AJAX应用程序，并且想用回调包装我们的响应，那么您要做的就是在任何API调用中指定一个回调参数：

https://api.instagram.com/v1/self/media/recent?access_token=ACCESS-TOKEN&callback=callbackFunction

Would respond with:将会回应：

callbackFunction({

    ...

});