Digi-Key APIは、OAuth 2.0 Authorization Frameworkを実装します。Oauth 2 Frameworkは、サードパーティアプリケーションに保護されたリソースへの安全なアクセスを委任する業界標準の方法です。DK APIに対して行うすべてのリクエストには、アクセストークンが必要です。
必要なスキルは、OAuth 2.0に精通していることと、OAuth 2.0で承認コードの付与フロー、承認エンドポイント、トークンエンドポイント、リダイレクションエンドポイント、ベアラートークン、リフレッシュトークンの利用に精通していることです。承認コードの付与フローは、DK APIにアクセスするために唯一許可されている方法です。
TLS
DK APIのリソースとサードパーティアプリケーションのリソースを保護するために、すべてのHTTPトラフィックはTLSv1.2暗号化プロトコルを使用して保護されます。クライアントアプリケーションは、TLSv1.2を使用するように開発されます。DKのリソースにアクセスする際には、エンドポイントを検証するとともに、エンドポイントがTLSを使用していることを確認してください。
アクセス制御
DK APIのリソースとサードパーティアプリケーションのリソースを保護するには、クライアントアプリケーションのクライアントIDとクライアントシークレットをプライベートに保ち、また保護する必要があります。サードパーティアプリケーションには、クライアントIDとクライアントシークレットが割り当てられます。クライアントIDとクライアントシークレットはどちらもサードパーティアプリケーションに一意です。これらは保護する必要があり、決して公開されてはなりません。
レート制限
DK API製品にはレート割り当て制限があります。 レート制限は製品ごとに適用されます。アプリケーションのレート(使用頻度)は、製品ごとにリクエスト回数/分とリクエスト回数/日の両方によって制限されます。
以下のレート制限は標準製品のものです。
標準製品 | レート制限/分 | レート制限/日 |
---|---|---|
バーコード | 120回/分 | 1000回/日 |
*バッチProductDetails | 10回/分 | 50回/日 |
BOMを作成する | 10回/分 | - |
注文サポート | 120回/分 | 1000回/日 |
注文 | 10回/分 | - |
製品情報 | 120回/分 | 1000回/日 |
見積 | 10回/分 | - |
*バッチProductDetailsには、1回のリクエストにつき最大50個の部品番号を格納することができます。
すべてのAPIレスポンスには、クライアントアプリケーションの使用状況を識別するために、次の一連のレスポンスヘッダーが付いています。
ヘッダー | 説明 |
---|---|
X-RateLimit-Limit |
ユーザーが1日に行うことができる最大リクエスト回数 |
X-RateLimit-Remaining |
現在設定されているレート制限枠内で行うことができる残りのリクエスト回数 |
アプリケーションがレート制限枠に達すると、クライアントアプリケーションは次のステータスコードを受け取ります。
429 Too Many Requests
バースト制限枠を超過すると、レスポンスヘッダーに次のように表示されます。
ヘッダー | 説明 |
---|---|
Retry-After | リクエストが再試行可能になるまでに待機する必要がある秒数 |
X-BurstLimit-Limit | 1分あたりにAPIをリクエストできる最大回数 |
X-BurstLimit-Remaining | 現在設定されているレート制限枠内で行うことができる残りのリクエスト回数 |
X-BurstLimit-Reset | バースト制限枠がリセットされるまでの秒数 |
X-BurstLimit-ResetTime | バースト制限枠がリセットされる時刻(GMT) |
JSONレスポンスメッセージは次のようになります。
{ "ErrorResponseVersion": "3.0.0.0", "StatusCode": 429, "ErrorMessage": "BurstLimit exceeded", "ErrorDetails": "Please try again after the number of seconds in the Retry-After header", "RequestId": "fa3e4d88-bfc4-4565-c6d5-a567633c091b", "ValidationErrors": [] }
1日あたりの制限枠を超過すると、以下のレスポンスヘッダーが表示されます。
ヘッダー | 説明 |
---|---|
Retry-After | リクエストが再試行可能になるまでに待機する必要がある秒数 |
X-RateLimit-Limit | APIをリクエストできる最大回数 |
X-RateLimit-Remaining | 現在設定されているレート制限枠内で行うことができる残りのリクエスト回数 |
X-RateLimit-Reset | 超過したレート制限枠がリセットされるまでの秒数 |
X-RateLimit-ResetTime | レート制限枠がリセットされる時刻(GMT) |
JSONレスポンスメッセージは次のようになります。
{ "ErrorResponseVersion": "3.0.0.0", "StatusCode": 429, "ErrorMessage": "Daily Ratelimit exceeded", "ErrorDetails": "Please try again after the number of seconds in the Retry-After header", "RequestId": "f4a0c1ab-8b47-4a72-e010-8ebe5d78f96c", "ValidationErrors": [] }
ステータスコード
各APIは、送信するステータスコードを記録します。返されるステータス(レスポンス)コードはRFC 22616仕様に従っています。通常、返されるステータスコードは次のとおりです。
HTTPステータスコード | 説明 |
---|---|
200OK |
成功しました。 |
400 Bad Request |
入力パラメータが正しくありません。 正しくないパラメータとそれが正しくない理由をエラーメッセージに表示する必要があります。 あなたのクライアントリクエストは形式が不正か、または無効です。 要求された部品が存在していなかった可能性もありますが、その可能性は高くありません。 |
401 Unauthorized |
クライアントが無効なアクセストークンを渡しました。 クライアントはトークンをリフレッシュしてから再度渡す必要があります。 または、クライアントアプリケーションでDK API製品を受信登録していません。 |
404 Not Found |
リソースが存在していません。 |
405 Method Not Allowed |
リソースは、指定されたHTTP動詞をサポートしていません。 形式が予期外であるリクエストを送信しようとしています。 このような例としては、POSTデータを表示する必要がある場合のGETリクエスト送信があります。 |
429 Too Many Requests |
リクエスト回数がレート制限を超過しました。特定の期間内のリクエスト回数が多すぎる(> 120/分)か、現在のレート制限で使用可能な回数を超過しました。 |
500 Internal Server Error |
サーバが予期したとおりに動作していません。 このリクエストはおそらく有効ですが、後で再度送信する必要があります。 |
503 Service Unavailable |
このサービスはご利用いただけません。 |
サポート
DK APIへのアクセスまたは使用に関する技術的なヘルプ情報については、サポートページをご覧ください。
開発者
Digi-KeyのAPIソリューションをご利用いただくには、クライアントアプリケーションのご登録が必要です。 クライアントアプリケーションを登録するには、https://developer.digikey.comからDigi-KeyのAPIソリューションのアカウントを作成してください。
アカウント作成後、開発者ポータルにログインします。ログインに成功すると、ナビゲーションバーに開発者の名前が表示されます。
開発者の名前をクリックしてドロップダウンメニューを開くと、Sandboxアプリケーションにアクセスが可能です。
Sandbox環境
Sandboxは、APIを使用してクライアントアプリケーションをテストできる安全な環境です。SandboxのAPIは、有効なデータ応答を提供しながらも、実際のリクエストは行いません。SandboxのAPIから返されるデータは完全なものではないかもしれませんが、その構造は本番環境のデータ構造と同じです。Sandboxは、開発者が最初にアクセスする環境です。
Sandboxの目的は、お客様のコードがDigi-KeyのAPI(承認と認証)と通信できるかをテストすることです。 受信した応答は正しいデータ構造を提供しますが、データ自体はリクエストと一致しない場合があります。
当社のAPIと通信可能であることが確認できたら、本番バージョンへの切り替えをお勧めします。
Sandboxアプリケーション
開発者は、Sandboxアプリケーションを作成します。Sandboxアプリケーションは、作成した開発者のみが利用できます。Sandboxアプリケーションは共有できません。
Sandboxアプリケーションの登録
最初に、開発者の名前をクリックしてドロップダウンメニューを開き、アプリケーションを選択します。
「Create Sandbox App」ボタンをクリックして、Sandboxアプリケーションを作成します。
Sandboxアプリケーションのフォームが表示されます。お客様のアプリケーションに関する情報をフォームに入力し、「Add sandbox app」ボタンをクリックしてSandboxアプリケーションを追加します。
Sandboxアプリケーションが作成されました。
Sandboxアプリケーションのプロパティの表示
アプリケーションのプロパティを表示するには、アプリケーション名をクリックします。アプリケーションを編集するには、「Edit」リンクをクリックします。
開発者が定義したアプリケーションのプロパティと、アプリケーションの認証情報が表示されます。
「Edit」タブを選択すると、開発者が定義したアプリケーションのプロパティを編集できます。
アプリケーションの削除
アプリケーションを削除するには、「My Sandbox Apps」ページで「Delete」リンクをクリックします。
または、アプリケーションのプロパティページで「Delete」タブをクリックしても削除できます。
アプリケーションを削除するかの確認メッセージが表示されます。削除する場合は、確認メッセージの下の文字列を入力して、「Delete」ボタンをクリックします。
アプリケーションが削除されました。
組織
Digi-Key APIを本番環境で呼び出すには、開発者は組織を作成するか、組織のメンバーである必要があります。組織には1人または複数のメンバーを含めることができます。作成した組織には共同開発者を招待する必要があります。組織の1人または複数のメンバーに、組織管理者の役割を割り当てることができます。組織管理者の役割は、選ばれたメンバーに組織のユーザーとアプリケーションの管理を許可することです。
会社は、会社の登記名またはドメイン名を使用して1つの組織を作成する必要があります。
本番環境
組織は本番アプリケーションを作成します。 本番アプリケーションは本番環境のAPIを呼び出します。
本番アプリケーション
本番アプリケーションは、本番環境のAPI/バックエンドサービスとの間でトラフィックを送受信します。本番環境とは、クライアントアプリケーションにとって「ライブ」環境です。本番アプリケーションは、組織で作成します。
組織が作成したすべてのアプリケーションは、本番アプリケーションです。組織のアプリケーションは、組織のメンバー間で共用できます。
組織アプリケーションの登録
組織アプリケーションを作成するには、前述のとおり、あなたが組織を作成しておくか、組織のメンバーとして追加されている必要があります。
まず、ナビゲーションバーの「組織」をクリックします。
次に、「Operations」の下にある「Production Apps」を選択します。
「Create Production App」ボタンをクリックして、本番アプリケーションを作成します。
アプリケーションに固有の情報を使用してフォームに入力し、「Add production app」ボタンをクリックします。
本番アプリケーションが作成されました。
組織アプリケーションのプロパティの表示
アプリケーションのプロパティを表示するには、アプリケーション名をクリックします。アプリケーションを編集するには、「Edit」リンクをクリックします。
開発者が定義したアプリケーションのプロパティと、アプリケーションの認証情報が表示されます。
「Edit」タブを選択すると、開発者が定義したアプリケーションのプロパティを編集できます。 「Delete」タブを選択すると、アプリケーションの削除を開始できます。
アプリケーションの削除
アプリケーションを削除するには、「Production Apps」ページで「Delete」リンクをクリックします。
または、アプリケーションのプロパティページで「Delete」タブをクリックしても削除できます。
アプリケーションの削除を確認するメッセージが表示されます。削除する場合は、確認メッセージの下の文字列を入力して、「Delete」ボタンをクリックします。
アプリケーションが削除されました。
組織管理者の役割
組織管理者の役割は、組織のメンバーを管理することです。この役割を持つメンバーは、組織の他の開発者の権限を管理できます。 また、組織管理者は、管理者の役割を他の開発者に割り当てることもできます。
組織へのメンバーの追加
新しいメンバーを組織に追加するには、招待するそのメンバーをあらかじめ開発者ポータルに登録しておく必要があります。組織管理者の役割を持つメンバーのみが、他の開発者を組織に追加することができます。
組織にメンバーを追加するには、「Members」ページで「Add member」ボタンをクリックします。
追加する開発者の正確な電子メールアドレスをフォームに入力し、組織管理者の役割を設定する必要があるかどうかを判断します。
当該の開発者が組織に追加されました。
組織からメンバーを削除する
メンバーを削除するには、削除するメンバーと同じ行にある「Remove」アイテムをクリックします。
次に、「Confirm」をクリックして、メンバーを削除することを確認します。
メンバーが組織から削除されました。
認証と承認
OAuthとDigi-Key APIの概要
承認シーケンスは、クライアントアプリケーションがブラウザをDigi-Key URLにリダイレクトしたときに開始されます。
そのURLには、リクエストされているアクセスのタイプを示すクエリパラメータが含まれます。
Digi-Keyの承認サーバは、ユーザー認証とユーザーの同意を処理します。 認証プロセス中に使用されるのは、開発者のMyDigiKeyユーザー名&パスワードでなく、エンドユーザーのユーザー名&パスワードです。
それらを入力すると、承認コードがDigi-Keyの承認サーバによってクエリ文字列に入れてアプリケーションに返されます。
クライアントアプリケーションは承認コードを受け取った後、そのコード(アプリケーションのクライアントIDとクライアントシークレットを使って要求されたもの)をアクセストークンとリフレッシュトークンと交換できます。
クライアントアプリケーションは、アクセストークンを使用して、購読しているDigi-Key APIにアクセスすることができます。
リフレッシュトークンを使用すれば、いつでも新しいアクセストークンを取得できます。 これは、アプリケーションが新しいアクセストークンをユーザーが直接取得する必要がないため、オフラインアクセスと呼ばれます。
基本的な手順
SandboxとProductionのどちらのクライアントアプリケーションも、OAuth 2.0フレームワークを使用してDigi-Key APIにリクエストを送信する場合は、基本的なパターンに従います。
大まかに言うと、次の4つのステップがあります。
アプリケーションを登録
アプリケーションを登録すると、OAuth2のクライアントIDとクライアントシークレットがアプリケーションに提供されます。 この情報をコピーし、クライアントアプリケーション用に確保します。
承認コードを取得し、アプリケーションへのアクセス権を付与
ユーザーにDigi-Keyアカウントにログインさせて自身で認証を行わせることにより、承認コードを取得します。 ユーザーはログイン後、承認をリクエストしているアプリケーションを承認するように求められます。 承認とは、アプリケーションにDigi-Keyアカウントへのアクセス権を付与することです。 ユーザーがアクセス権を与えると、Digi-Keyの承認サーバがアプリケーションに承認コードを送信します。 ユーザーがアクセス権を与えない場合、承認サーバはエラーを返します。
アクセストークンを取得
承認コード、クライアントID、クライアントシークレット、付与タイプを承認サーバのトークンエンドポイントに送信して、アクセストークンを取得します。 アクセストークンとリフレッシュトークンが送信されます。
アクセストークンをAPIに送信
クライアントアプリケーションは、リクエストヘッダーを使ってアクセストークンを渡すことで、購読しているDK APIへのリクエスト送信が可能になりました。アクセストークンの有効期間が満了すると、クライアントアプリケーションは、保存しているリフレッシュトークンを送信して、新しい認証情報のセットを受け取ることができます。
Sandboxアプリケーション
以下に記載するのは、SandboxアプリケーションのOAuthプロセスを実行するために必要な情報です。 実行に進む前に確認が必要な項目としては、クライアントアプリケーションが登録されていること、クライアントIDとクライアントシークレットが保存・保護されていること、クライアントアプリケーションがSandbox API製品を購読していることがあります。
承認コードを取得
ユーザー認証のエンドポイントはブラウザで行われます。
Sandbox承認エンドポイント | 説明 |
https://sandbox-api.digikey.com/v1/oauth2/authorize | このエンドポイントは、初期リクエストのターゲットであり、 ユーザーの認証とユーザーの同意を処理します。 結果として、承認コードが返されます。 |
エンコードされたURLをブラウザで送信するために必要なクエリパラメータのセット:
パラメータ | 値 | 説明 |
response_type | コード | 承認コードを返すように承認サーバに指示します。 |
client_id | 登録済みアプリケーションに割り当てられているクライアントID | リクエストを行っているクライアントアプリケーションを識別します。 このパラメータで渡される値は、割り当てられている値と正確に一致する必要があります。 |
redirect_uri | 開発者が設定するリダイレクトURI | レスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI(末尾の「/」も含む)と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。 |
state(オプション) | リクエストとコールバックの間で状態を維持するためにクライアントが使用する不透明な値 | 承認サーバは、ユーザーエージェントをクライアントにリダイレクトするときにこの値を追加します。このパラメータは、クロスサイトリクエストの偽造を防止するために使用する必要があります。 |
必要なクエリパラメータによって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エンコードを表しています。文字「:」は「%3A」として、また、 文字「/」は「%2F」として、それぞれURLエンコードされています。
これらは次のようにブラウザでも確認できます。
レスポンスを処理
レスポンスは、リクエストURLで指定したリダイレクトURIに送信されます。 ユーザーがアクセスリクエストを承認すると、承認コードがレスポンスとして出力されます。 承認しない場合は、レスポンスとしてエラーメッセージが出力されます。 以下に示すように、すべてのレスポンスはブラウザのクエリ文字列として出力されます。
エラーとしてのレスポンス:
https://client-app-redirect-uri/code?error=access_denied
承認コードとしてのレスポンス:
https://client-app-redirect-uri/?code=lboI52TG&scope=&state=null
注:承認コード(例:lboI52TG)は作成から1分で有効期間が満了になります。
アクセストークンを取得
ブラウザが承認コードを受け取った後、アプリケーションは承認コードをアクセストークンとリフレッシュトークンと交換することができます。 トークンの取得に使用するURLは次のとおりです。
Sandboxアクセストークンエンドポイント | 説明 |
https://sandbox-api.digikey.com/v1/oauth2/token | このエンドポイントは2番目のリクエストのターゲットです。 このエンドポイントへのリクエストの結果には、アクセストークンとリフレッシュトークンが含まれます |
アクセストークンのリクエストは、HTTPS POSTリクエストであり、以下のx-www-form-urlencodedデータを指定する必要があります。
パラメータ | 説明 |
コード | 最初のリクエストに対して返された承認コードです。承認コードは作成後1分で有効期間が満了になります。 |
client_id | これは、APIポータル内で生成したアプリケーションに割り当てられるクライアントIDです。 |
client_secret | これは、APIポータル内で生成したアプリケーションに割り当てられるクライアントシークレットです。 |
redirect_uri | レスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI(末尾の「/」も含む)と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。 |
grant_type | OAuth 2.0の仕様で定義されているように、このフィールドには値authorization_codeを設定する必要があります。 |
実際のリクエストの例は次のとおりです。
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
このリクエストの成功時のレスポンスには、以下のフィールドが含まれます。
フィールド | 説明 |
access_token | Digi-Key APIにアクセスするために送信されるトークン |
refresh_token | 新しいアクセストークンを取得するために送信するトークン |
expires_in | アクセストークンの有効期間の残り(単位:秒) |
refresh_token_expires_in | リフレッシュトークンの有効期間の残り(単位:秒) |
token_type | 返されるトークンタイプ |
成功時のレスポンスは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
このリクエストには、以下の必須パラメータのセットを含める必要があります。
パラメータ | 説明 |
client_id | 登録済みアプリケーションに割り当てられているクライアントID |
client_secret | 登録済みアプリケーションに割り当てられているクライアントシークレット |
refresh_token | 送信する保存済みのリフレッシュトークン |
grant_type | OAuth 2.0の仕様で定義されているように、このフィールドにはrefresh_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製品を購読していることがあります。
承認コードの取得
ユーザー認証のエンドポイントはブラウザで行われます。
本番承認エンドポイント | 説明 |
https://api.digikey.com/v1/oauth2/authorize | このエンドポイントは、初期リクエストのターゲットであり、 ユーザーの認証とユーザーの同意を処理します。 結果として、承認コードが返されます。 |
エンコードされたURLをブラウザで送信するために必要なクエリパラメータのセット:
パラメータ | 値 | 説明 |
response_type | コード | 承認コードを返すように承認サーバに指示します。 |
client_id | 登録済みアプリケーションに割り当てられているクライアントID | リクエストを行っているクライアントを識別します。 このパラメータで渡される値は、APIポータルによって割り当てられている値と正確に一致する必要があります。 |
redirect_uri | 開発者が設定するリダイレクトURI | レスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI(末尾の「/」も含む)と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。 |
state(オプション) | リクエストとコールバックの間で状態を維持するためにクライアントが使用する不透明な値 | 承認サーバは、ユーザーエージェントをクライアントにリダイレクトするときにこの値を追加します。このパラメータは、クロスサイトリクエストの偽造を防止するために使用する必要があります。 |
必要なクエリパラメータによってURLエンコードされたコードリクエストの例:
https://api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F
上記の例の太字は、文字のURLエンコードを表しています。文字「:」は「%3A」として、また、 文字「/」は「%2F」として、それぞれURLエンコードされています。
これらは次のようにブラウザでも確認できます。
レスポンスを処理
レスポンスは、リクエストURLで指定したリダイレクトURIに送信されます。 ユーザーがアクセスリクエストを承認すると、承認コードがレスポンスとして出力されます。 承認しない場合は、レスポンスとしてエラーメッセージが出力されます。 以下に示すように、すべてのレスポンスはブラウザのクエリ文字列として出力されます。
エラーとしてのレスポンス:
https://client-app-redirect-uri/code?error=access_denied
承認コードとしてのレスポンス:
https://client-app-redirect-uri/code?code=lboI52TG&scope=&state=null
注:承認コード(例:lboI52TG)は作成から1分で有効期間が満了になります。
アクセストークンを取得
ブラウザが承認コードを受け取った後、アプリケーションは承認コードをアクセストークンとリフレッシュトークンと交換することができます。 トークンの取得に使用するURLは次のとおりです。
本番アクセストークンエンドポイント | 説明 |
https://api.digikey.com/v1/oauth2/token | このエンドポイントは2番目のリクエストのターゲットです。 このエンドポイントへのリクエストの結果には、アクセストークンとリフレッシュトークンが含まれます |
アクセストークンのリクエストは、HTTPS POSTリクエストであり、以下のx-www-form-urlencodedデータを指定する必要があります。
フィールド | 説明 |
コード | 最初のリクエストに対して返された承認コードです。 承認コードは作成後1分で有効期間が満了になります。 |
client_id | 登録済みアプリケーションに割り当てられているクライアントID |
client_secret | 登録済みアプリケーションに割り当てられているクライアントシークレット |
redirect_uri | レスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI(末尾の「/」も含む)と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。 |
grant_type | OAuth 2.0の仕様で定義されているように、このフィールドには値authorization_codeを設定する必要があります。 |
承認コード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
このリクエストの成功時のレスポンスには、以下のフィールドが含まれます。
フィールド | 説明 |
access_token | Digi-Key APIにアクセスするために送信されるトークン |
refresh_token | 新しいアクセストークンを取得するために送信するトークン |
expires_in | アクセストークンの有効期間の残り(単位:秒) |
refresh_token_expires_in | リフレッシュトークンの有効期間の残り(単位:秒) |
token_type | 返されるトークンタイプ |
成功時のレスポンスは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
このリクエストには、以下の必須パラメータのセットを含める必要があります。
フィールド | 説明 |
client_id | 登録済みアプリケーションに割り当てられているクライアントID |
client_secret | 登録済みアプリケーションに割り当てられているクライアントシークレット |
refresh_token | 送信する保存済みのリフレッシュトークン |
grant_type | OAuth 2.0の仕様で定義されているように、このフィールドにはrefresh_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", }
注:新しいアクセストークンを取得するたびに、リフレッシュトークンが再生成されます。 古いリフレッシュトークンは無効になるため、必ず最新のリフレッシュトークンを保存してください。
コードとトークンの有効期間
すべてのコードとトークンには有効期間があります。
タイプ | 有効期間 |
承認コード | 1分 |
アクセストークン | 30分 |
リフレッシュトークン | 90日 |
API呼び出しを行う
OAuthが完了すると、アプリケーションによるリクエスト送信が可能になります。
開発者Sandboxアプリケーションのリクエスト例
開発者の認証情報とエンドポイント(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
Authorizationヘッダーの値の前には「Bearer」が付きます。
例:"Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"
値「Bearer」はBearerTokenと一緒に送信する必要があります。そうしない場合は、ベアラートークンエラーが発生します。
"Authorization":"Bearer <ベアラートークン>"