Documentation

 开发者

开发者可注册客户端应用程序来访问 DK API 解决方案。 开发者要注册应用程序，必须在 https://developer.digikey.com 上创建 DK API 解决方案账户。 

成功注册后，开发者将登录到开发者门户。登录成功即会在导航栏显示开发者名称：

选择开发者名称下拉列表，即可看到开发者现在已经能够访问沙盒，并且可以创建沙盒应用程序。

沙盒

沙盒应该是一种安全的测试方法，能够针对 API 对客户端应用程序开发进行测试。此时 API 会提供有效的数据响应结构，但不会实际发出生产请求。虽然从沙盒 API 返回的数据可能不完整，但沙盒 API 响应的结构将代表生产中的预期结果。沙盒是开发者可以访问的第一个环境。

沙盒的目的是测试您的代码与 Digi-Key API的通信能力（授权和认证）。 收到的响应会具有正确的数据结构，但数据本身可能与您的请求不匹配。

当您确认您有能力与我们的 API 通信后，建议您切换到生产版本。

沙盒应用程序

开发者创建沙盒应用程序。沙盒应用程序仅可供其创建者使用。沙盒应用程序不能共享。

注册沙盒应用程序

首先选择开发者名称下的下拉菜单，然后选择“应用程序”：

单击“创建沙盒应用程序”按钮：

使用您的具体应用程序信息填写表单，然后单击“添加沙盒应用程序”按钮：

沙盒应用程序已创建：

查看沙盒应用程序属性

要查看应用程序属性，请单击应用程序名称。要编辑应用程序，请单击“编辑”链接。

这里既能看到开发者为应用程序定义的属性，也能看到给应用程序注册的一组凭证：

选择“编辑”选项卡，您可以编辑开发者定义的应用程序属性。

删除应用程序

在“我的沙盒应用程序”页面上可以删除应用程序：

或在查看应用程序属性页面时单击“删除”选项卡：

网站会要求您输入并提交指定字符串，以确认您想要删除该应用程序：

该应用程序即被删除：

2 Legged Authorization

Basic Steps

All client applications, both Sandbox and Production, follow a basic pattern when making requests to a DigiKey API with the OAuth 2.0 framework.

At a high level, there are three steps:

Register an Application

When you register an application, it will be provisioned an OAuth2 client ID and client secret. Copy and secure this information for your client application.

Get an access token

Get an access token by sending the client id, client secret, and grant type to the authorization server’s token endpoint. You will receive an access token.

Send the access token to an API

By passing the access token with a request header, the client application can now make requests to the DK API it is subscribed to. When the access token expires, a new request must be made.

Sandbox Application

Contained below is the necessary information to complete the 2 legged OAuth process for Sandbox Applications. Before continuing, please confirm that a client application is registered, its client id and client secret are stored and secured, and its subscribed to a Sandbox API Product.

Getting the Access Token

The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:

An example of an access token POST request (this is not query parameter):

POST /v1/oauth2/token HTTP/1.1 
Host: sandbox-api.digikey.com 
Content-Type: application/x-www-form-urlencoded 
code=lboI52TG& client_id=application_client_id& 
client_secret=application_client_secret& grant_type= client_credentials

A successful response to this request contains the following fields:

A successful response is returned as a JSON object.

Example response to a successful access token request:

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds" 
"expires_in": 599, "token_type": "BearerToken", }

Note: Other fields may be included in the response, and your application should not treat this as an error. The set shown above is the minimum set.

Production Application

Contained below is the necessary information to complete the OAuth process for Production Applications. Before continuing please confirm that a client application is registered, its client id and client secret are stored and secured, and its subscribed to a Production API Product.

Getting the Access Token

The URL used to get your token is:

The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:

An example of an access token POST request (this is not query parameter):

POST /v1/oauth2/token HTTP/1.1 
Host: api.digikey.com 
Content-Type: application/x-www-form-urlencoded 
code=lboI52TG& client_id={application_client_id}& 
client_secret={application_client_secret}& grant_type=client_credentials 

A successful response to this request contains these fields:

A successful response is returned as a JSON object.

Example response to a successful access token request:

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", 
"expires_in": 599, "token_type": "Bearer", } 

Note: Other fields may be included in the response, and your application should not treat this as an error. The set shown above is the minimum set.

Token Expiration Time

Making an API Call

With OAuth completed the application can send a request.

Developer application example request (Sandbox)

Example request to ProductSearch using developer credentials and endpoint (sandbox-api.digikey.com) :

GET /products/v4/search/P5555-ND/productdetails HTTP/1.1 
Host: sandbox-api.digikey.com 
X-DIGIKEY-Client-Id: WugAd2A6Lxy3Eu3Mgvov45KUNoguMoUl 
Authorization: Bearer StgGLw9b3hkwqlWAGBmdYoBNEokm 
X-DIGIKEY-Locale-Site: US 
X-DIGIKEY-Locale-Language: en 
X-DIGIKEY-Locale-Currency: USD 
X-DIGIKEY-Customer-Id: 0

Organization application example request (Production)

Example request to ProductSearch using organization credentials and endpoint (api.digikey.com):

GET /products/v4/search/P5555-ND/productdetailsHTTP/1.1 
Host: api.digikey.com 
X-DIGIKEY-Client-Id: heWGx9w6DK8kZf3jRv5E9jUAhXrGBU67 
Authorization: Bearer s4T5DbmFZadjNRAEbUnN9zkU3DBj 
X-DIGIKEY-Locale-Site: US 
X-DIGIKEY-Locale-Language: en 
X-DIGIKEY-Locale-Currency: USD 
X-DIGIKEY-Customer-Id: 0

The Value of the Authorization header is prefixed with "Bearer"

e.g.: "Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"

The value "Bearer" must be sent with the BearerToken or else you will get a Bearer token error.

"Authorization":"Bearer <BearerToken>"

验证与授权

OAuth 和 Digi-Key API 概述

当客户端应用程序将浏览器重定向到 Digi-Key URL 时，授权序列开始。

该 URL 包含指明所请求访问类型的查询参数。

Digi-Key 的授权服务器负责处理用户验证和用户准许。 在验证过程中，使用的是最终用户的“我的 Digi-Key”用户名和密码（而不是开发者的用户名和密码）。

结果返回一个授权码，是由 Digi-Key 的授权服务器以查询字符串的形式返回到您的应用程序的。
客户端应用程序在收到授权码后，可以将该代码（用应用程序的客户端 ID 和客户端密钥进行请求）交换成访问令牌和刷新令牌。

然后，客户端应用程序可以使用访问令牌访问它已订阅的 Digi-Key API。
刷新令牌可用于随时获取新的访问令牌。 这就是所谓的离线访问，因为当应用程序获取新的访问令牌时，用户不必在场。

基本步骤

所有客户端应用程序，同时包括沙盒和生产环境，在使用 OAuth 2.0 框架向 Digi-Key API 发出请求时，都会遵循一基本模式。
总体来说，有四步：

创建应用程序

当您创建应用程序时，将被提供一个 OAuth2 客户端 ID 和客户端密钥。 复制该信息并确保其安全，以备您的客户端应用程序将来使用。

获取授权码并授予应用程序访问权

通过让用户登录自己的 Digi-Key 账户自行进行身份验证，从而获得授权码。 登录后，系统会要求用户对请求的应用程序进行授权。 授权会给应用程序授予对 Digi-Key 账户的访问权。 如果用户授予权限，Digi-Key 的授权服务器就会向应用程序发送一个授权码。 如果用户没有授予权限，授权服务器就会返回一个错误。

获取访问令牌

通过向授权服务器的令牌端点发送授权码、客户端 ID、客户端密钥和授予类型来获取访问令牌。 您将收到一个访问令牌和一个刷新令牌。

将访问令牌发送至 API

通过传递带有请求报头的访问令牌，客户端应用程序现在可以向其订阅的 DK API 发出请求。当访问令牌过期时，客户端应用程序可以提交存储的刷新令牌来接收新一组凭证。

沙盒应用程序

以下是完成用于沙盒应用程序的 OAuth 进程的必要信息。 在继续前，请确认客户端应用程序已经注册，其客户端 ID 和客户端密钥已被存储和保护，并且订阅了沙盒 API 产品。

获取授权码

用于用户验证的端点，这在浏览器中完成：

在浏览器中发送 url 编码所需的一组查询参数。

url 编码的代码请求和所需的查询参数实例：

https://sandbox-api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F

在上面的例子中，粗体突出显示了字符的 url 编码。字符 ":" 的 url 编码为 "%3A"。 字符 "/" 的 url 编码为 "%2F"

如浏览器中所见：

处理响应

响应将按照请求 URL 中的指定，发送到重定向 URI。 如果用户批准访问请求，那么响应就会包含一个授权码。 如果用户不批准该请求，则响应会包含一个错误信息。 所有响应都会通过查询字符串返回浏览器，如下所示：

一个错误响应：

https://client-app-redirect-uri/code?error=access_denied

一个授权码响应：

https://client-app-redirect-uri/?code=lboI52TG&scope=&state=null

注意：代码（例如：lboI52TG）在创建后将在一分钟内失效。

获取访问令牌

浏览器收到授权码后，您的应用程序可能会用授权码交换一个访问令牌和一个刷新令牌。 用于获取令牌的 URL 是：

访问令牌的请求是一个 HTTPS POST 请求，必须包含以下 x-www-form-urlencoded 数据：

实际请求可能像下面这样：

POST /v1/oauth2/token HTTP/1.1 Host: sandbox-api.digikey.com Content-Type: application/x-www-form-urlencoded code=lboI52TG& client_id=application_client_id& client_secret=application_client_secret& redirect_uri=https://client-app-redirect-uri& grant_type=authorization_code

对该请求的成功响应包含以下字段：

成功响应作为 JSON 对象返回。

成功访问令牌请求的示例响应：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注意：响应中可能包含其他字段，您的应用程序不应将其视为错误。 上面显示的集合是最小的集合。

使用刷新令牌

如上节所述，当您获得初始访问令牌时，会获得一个刷新令牌。 在这些情况下，您的应用程序可以通过向 Digi-Key 的授权服务器发送刷新令牌来获得新的访问令牌。

为了以这种方式获得新的访问令牌，您的应用程序需要向令牌端点发送一个 HTTPS POST 请求。

https://sandbox-api.digikey.com/v1/oauth2/token

该请求必须包括这组必须的参数：

这样的请求看起来会类似下面这个样子：

POST /v1/oauth2/token HTTP/1.1 Host: sandbox-api.digikey.com Content-Type: application/x-www-form-urlencoded client_id=application_client_id& client_secret=application_client_secret& refresh_token=123Asfeksodk/jkdsoieDSioIOS-483LidkOOl& grant_type=refresh_token

只要用户没有撤销授予您应用程序的访问权，响应就会提供一组新的令牌。

成功刷新令牌请求的示例响应：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注意：每次获得新的访问令牌时，刷新令牌都会重新生成。 请务必保存最新的刷新令牌，因为旧的令牌将不再有效。

生产应用程序

以下是完成针对生产应用程序的 OAuth 进程必需的信息。 在继续前，请确认客户端应用程序已经注册，其客户端 ID 和客户端密钥已被存储和保护，并且订阅了生产 API 产品。

获取授权码

用于用户验证的端点，这在浏览器中完成：

在浏览器中发送 url 编码所需的一组查询参数。

url 编码的代码请求和所需的查询参数实例：

https://api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2

在上面的例子中，粗体突出显示了字符的 url 编码。字符 ":" 的 url 编码为 "%3A"。 字符 "/" 的 url 编码为 "%2F"

如浏览器中所见：

处理响应

响应将按照请求 URL 中的指定，发送到重定向 URI。 如果用户批准访问请求，那么响应就会包含一个授权码。 如果用户不批准该请求，则响应会包含一个错误信息。 所有响应都会通过查询字符串返回浏览器，如下所示：

一个错误响应：

https://client-app-redirect-uri/code?error=access_denied

一个授权码响应：

https://client-app-redirect-uri/code?code=lboI52TG&scope=&state=null

注意：代码（例如：lboI52TG）在创建后将在一分钟内失效。

获取访问令牌

浏览器收到授权码后，您的应用程序可能会用授权码交换一个访问令牌和一个刷新令牌。 用于获取令牌的 URL 是：

访问令牌的请求是一个 HTTPS POST 请求，必须包含以下 x-www-form-urlencoded 数据：

一个授权码 POST 请求实例：

POST /v1/oauth2/token HTTP/1.1 Host: api.digikey.com Content-Type: application/x-www-form-urlencoded code=lboI52TG& client_id={application_client_id}& client_secret={application_client_secret}& redirect_uri=https://client-app-redirect-uri& grant_type=authorization_code

对该请求的成功响应包含这些字段：

成功响应作为 JSON 对象返回。

成功访问令牌请求的示例响应：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注意：响应中可能包含其他字段，您的应用程序不应将其视为错误。 上面显示的集合是最小的集合。

使用刷新令牌

如上节所述，当您获得初始访问令牌时，会获得一个刷新令牌。 在这些情况下，您的应用程序可以通过向 Digi-Key 的授权服务器发送刷新令牌来获得新的访问令牌。

为了以这种方式获得新的访问令牌，您的应用程序需要向令牌端点发送一个 HTTPS POST 请求。

https://api.digikey.com/v1/oauth2/token

该请求必须包括这组必须的参数：

一个刷新令牌 POST 请求实例：

POST /v1/oauth2/token HTTP/1.1 Host: api.digikey.com Content-Type: application/x-www-form-urlencoded client_id={application_client_id}& client_secret={application_client_secret}& refresh_token=123Asfeksodk/jkdsoieDSioIOS-483LidkOOl& grant_type=refresh_token

只要用户没有撤销授予您应用程序的访问权，响应就会提供一组新的令牌。

成功刷新令牌请求的示例响应：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注意：每次获得新的访问令牌时，刷新令牌都会重新生成。 请务必保存最新的刷新令牌，因为旧的令牌将不再有效。

代码和令牌有效期

所有代码和令牌都有有效期。

进行 API 调用

OAuth 完成后，应用程序即可发送请求。

开发者应用程序示例请求（沙盒）

使用开发者凭证和端点 (sandbox-api.digikey.com) 向 PartSearch 发出的示例请求：

GET /Search/v3/Products/p5555-nd HTTP/1.1 Host: sandbox-api.digikey.com X-DIGIKEY-Client-Id: WugAd2A6Lxy3Eu3Mgvov45KUNoguMoUl Authorization: Bearer StgGLw9b3hkwqlWAGBmdYoBNEokm X-DIGIKEY-Locale-Site: US X-DIGIKEY-Locale-Language: en X-DIGIKEY-Locale-Currency: USD X-DIGIKEY-Locale-ShipToCountry: us X-DIGIKEY-Customer-Id: 0

组织应用程序示例请求（生产）

使用组织凭证和端点 (api.digikey.com) 向 PartSearch 发出的示例请求：

GET /Search/v3/Products/p5555-nd HTTP/1.1 Host: api.digikey.com X-DIGIKEY-Client-Id: heWGx9w6DK8kZf3jRv5E9jUAhXrGBU67 Authorization: Bearer s4T5DbmFZadjNRAEbUnN9zkU3DBj X-DIGIKEY-Locale-Site: US X-DIGIKEY-Locale-Language: en X-DIGIKEY-Locale-Currency: USD X-DIGIKEY-Locale-ShipToCountry: us X-DIGIKEY-Customer-Id: 0

授权报头的值带有 "Bearer" 前缀

例如："Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"

值 "Bearer" 必须和 BearerToken 一起发送，否则会收到一个Bearer 令牌错误。

"Authorization":"Bearer <BearerToken>"