目錄
Do you need to authenticate?(您需要認證嗎)
Receiving an access_token(接收一個access_token)
Server-side (Explicit) Flow(服務器端（顯式）流程)
Step Two: Receive the redirect from Instagram
Step Three: Request the access_token
Client-Side (Implicit) Authentication(客戶端（隱式）身份驗證)
Step One: Direct your user to our authorization URL
Step Two: Receive the access_token via the URL fragment
Login Permissions (Scopes)登錄權限（範圍）
Valid use cases and associated scopes(有效的用例和相關範圍)
How to Submit for Permissions Review
Disable Client-Side (Implicit) Authentication
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:
-
Direct the user to our authorization url.
-
-
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.
-
-
The server will redirect the user in one of two ways that you choose:
-
-
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，您必須執行以下操作：
-
將用戶定向到我們的授權URL。
-
-
如果用戶未登錄，則將要求他們登錄。
-
系統將詢問用戶是否要授予您的應用程序對其Instagram數據的訪問權限。
-
-
服務器將以您選擇的兩種方式之一重定向用戶：
-
-
服務器端流（推薦）：將用戶重定向到您選擇的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
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
注意：您可以提供一個可選的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? |
|
yes |
||
|
yes |
||
|
no |
||
|
yes |
||
|
no |
||
|
no |
||
|
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
It is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.
第二步：從Instagram接收重定向
一旦用戶授權了您的應用程序，我們就會在第三步中使用代碼參數向您的redirect_uri發出重定向。
請注意，您的重定向URI的主機和路徑組件必須與您註冊的redirect_uri完全匹配（包括斜槓）。如果需要動態更改行爲，還可以在提供的redirect_uri中包括其他查詢參數。例子：
|
註冊重定向URI |
傳遞給/ AUTHORIZE的REDIRECT_URI參數 |
有效？ |
|
是 |
||
|
是 |
||
|
沒有 |
||
|
是 |
||
|
沒有 |
||
|
沒有 |
||
|
是 |
如果用戶拒絕了您的批准請求，那麼我們將使用以下參數將用戶重定向到您的redirect_uri：
-
錯誤：access_denied
-
error_reason：user_denied
-
error_description：用戶拒絕了您的請求
您有責任在這種情況下正常失敗並向用戶顯示相應的錯誤消息。
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' \
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' \
如果成功，此調用將返回一個整齊打包的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
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
在這一點上，我們向用戶顯示一個登錄屏幕，然後是一個確認屏幕，在該屏幕上，他們向您的應用授予訪問其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
<?php
function generate_sig($endpoint, $params, $secret) {
$sig = $endpoint;
ksort($params);
foreach ($params as $key => $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=<your_access_token>' \
-F 'sig=<your_signature>' \
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({
...
});