以降のセクションでは、API プロダクトおよびそれに関連する主要なコンセプトについて紹介します。
API プロダクトとは
API プロバイダは API をバンドルする API プロダクトを作成することにより、アプリ デベロッパーがそれらを使用できるようにします。API プロダクトをプロバイダの製品ラインと見なすことができます。
具体的には、API プロダクトは次の要素をバンドルします。
- API リソース（URI）のコレクション
- サービスプラン
- モニタリングまたは分析に使用される、ビジネスに固有のメタデータ（オプション）
API プロダクトにバンドルする API リソースを 1 つ以上の API から集めることができるので、次の図に示すように、リソースを組み合わせて特化した機能セットを作成できます。
特定のニーズを満たすユースケース用に、多数の API プロダクトを作成できます。たとえば、多くのマッピング リソースをバンドルした API プロダクトを作成すると、デベロッパーはアプリケーションに簡単に地図を導入できます。また、さまざまに異なる価格レベルなど、API プロダクトごとに異なるプロパティを設定できます。たとえば、次の API プロダクトを組み合わせて提供できます。
- 1 つ目の API プロダクトは、アクセス回数の上限を低く（1 日あたり 1,000 リクエストなど）して、バーゲン価格で提供します。2 つ目の API プロダクトは、同じリソースにアクセスできる一方、アクセス回数の上限を高くして、価格も高くします。
- 1 つ目の無料 API プロダクトでは、リソースへの読み取り専用アクセスを提供します。2 つ目の API プロダクトでは、わずかな料金を課して、同じリソースへの読み取り / 書き込みアクセスを可能にします。
また、API プロダクトで API リソースに対するアクセスを制御することもできます。たとえば、社内のデベロッパーのみがアクセスできるリソースをバンドルしたり、料金を支払った顧客だけがアクセスできるリソースをバンドルしたりできます。
API 製品は、API の承認とアクセス制御を行う中心的なメカニズムです。Apigee では、API 自体ではなく、API 製品に対して API キーがプロビジョニングされます。言い換えると、リソースのバンドルに関して API キーがプロビジョニングされ、サービスプランがそれに関連付けられます。
アプリ デベロッパーが API プロダクトにアクセスするには、「アプリの登録」で説明されている方法でアプリを登録します。アプリが API プロダクトにアクセスしようとすると、実行時に Apigee が承認プロセスを適用し、次の条件が満たされることを確認します。
- リクエスト元のアプリは、特定の API リソースへのアクセスを許可されている。
- リクエスト元のアプリは、許可された割り当てを超えていない。
- API プロダクトで OAuth スコープが定義されている場合、それらのスコープが、アプリで提示されるアクセス トークンに関連付けられたスコープと一致している。
主要なコンセプトを理解する
API プロダクトを作成する前に、以下のキーのコンセプトを確認します。
API キー
デベロッパーのアプリを組織で登録する際には、そのアプリに 1 つ以上の API プロダクトを関連付ける必要があります。アプリを 1 つ以上の API プロダクトに関連付けると、Edge は一意のコンシューマ キーをそのアプリに割り当てます。
コンシューマ キーまたはアクセス トークンは、リクエストの認証情報として機能します。アプリ デベロッパーはコンシューマ キーをアプリに埋め込みます。これにより、Edge でホストされる API にアプリがリクエストを送信するとき、次のいずれかの方法でアプリはそのリクエスト内でコンシューマ キーを渡すことができます。
- API で API キー検証を使用する場合、アプリはコンシューマ キーを直接渡す必要があります。
- API で OAuth トークン検証を使用する場合、アプリはコンシューマ キーから生成されたトークンを渡す必要があります。
API キーの適用は自動的には行われません。リクエストの認証情報としてコンシューマ キーまたは OAuth トークンのどちらを使用する場合でも、API プロキシは適切なフローに VerifyAPIKey ポリシーまたは OAuth/VerifyAccessToken ポリシーを含めることによって、API プロキシのリクエスト認証情報を検証します。API プロキシに認証情報の適用ポリシーが含まれていない場合、どの呼び出し元からでも API を呼び出せます。詳細については、API キーポリシーを検証するをご覧ください。
リクエストで渡された認証情報を検証するために、Edge は次のステップを実行します。
- リクエストで渡される認証情報を取得します。OAuth トークンを検証する場合、Edge はそのトークンの有効期限が切れていないことを検証してから、トークンの生成に使われたコンシューマ キーを調べます。
- コンシューマ キーに関連付けられている API プロダクトのリストを取得します。
- 現行の API プロキシが API プロダクトに含まれていること、現行のリソースパス（URL パス）が API プロダクトで有効になっていることを確認します。
- コンシューマ キーが期限切れまたは取り消し済みでないこと、アプリが取り消し済みでないこと、さらにアプリ デベロッパーがアクティブであることを確認します。
上記のチェックにすべて合格すると、認証情報の検証が成功します。
まとめると、Edge がコンシューマ キーを自動生成しますが、API パブリッシャーは適切なポリシーを使用して API プロキシ内でキー検証を実施する必要があります。
自動承認と手動承認
デフォルトでは、アプリから API プロダクトにアクセスするためのキー取得リクエストが送信されると、すべて自動的に承認されます。別の方法として、手動でキーを承認するように API プロダクトを構成することもできます。この場合、API プロダクトを追加するアプリからのキーリクエストを、プロバイダが承認する必要があります。詳細については、アプリを登録して API キーを管理するをご覧ください。
割り当て
割り当てにより、高トラフィックに備えてバックエンド サーバーが保護され、プロダクト ラインが区別化されます。たとえば、割り当て量の高いリソースをプレミアム プロダクトとしてバンドルし、割り当て量の低い同じバンドルを基本プロダクトとして使用できます。割り当てを利用すれば、プロダクトの需要が高まって大量のリクエストを受信するようになった場合にサーバーが過負荷状態になるのを防止できます。
割り当ての構成については、割り当てポリシーをご覧ください。割り当てポリシーでプロダクト割り当て設定を使用する方法については、API プロダクトの割り当ての設定が API プロキシの割り当てポリシーと連動する仕組みに関するコミュニティの記事をご覧ください。
OAuth スコープ
追加のセキュリティ レベルとして、プロダクトを介して送信されるアクセス トークンに含まれる必要がある OAuth スコープをカンマ区切りリスト形式で定義できます。プロダクトを作成するときには、組織が使用するすべてのスコープを認識している必要があります。プロダクトに追加するスコープは、既存のスコープと一致している必要があります。そうでない場合、そのプロダクトは安全ではなくなります。
Edge OAuth ポリシーでスコープを使用する方法については、OAuth2 スコープの操作をご覧ください。
アクセスレベル
API プロダクトを定義する際に、次のアクセスレベルを設定できます。
| アクセスレベル | 説明 |
|---|---|
| Public | すべてのデベロッパーが使用できる API プロダクト。これらのプロダクトを、統合ポータルまたは Drupal ベースのデベロッパー ポータルに追加できます。 |
| Private または Internal only | 非公開または内部専用として使用される API プロダクト。 注: 限定公開と社内専用のアクセスレベルに違いはありません。API プロダクトの対象ユーザーを最もよく表しているラベルを選択します。 統合ポータルでは、必要に応じて非公開または内部専用 API プロダクトを追加してアプリ デベロッパーに使用を許可できます。 Drupal ベースのデベロッパー ポータルでは、以降のセクションで説明するように、デベロッパー ポータル上の非公開または内部専用 API プロダクトへのアクセスを管理できます。
|