【APIM連載第1回】Azure API Management 入門 - API管理を始めよう

Azure API Management（APIM）は、APIのライフサイクル全体を一元管理できるフルマネージドサービスです。

APIを公開・管理する際のセキュリティ、認証、レート制限、監視などの複雑な要件に対し、APIMは統合的なソリューションを提供します。

本記事では、これからAPIMを使い始める方、API管理をより効率化したい方に向けて、APIMの基本的な概念、主要機能、そして実際にAzure Portal上でAPIMインスタンスを作成し、最初のAPIを登録するまでの手順を詳しく解説します。

この記事を読むとできるようになることは以下の通りです。

APIMの基本機能とAPI管理の仕組みを理解できる
APIMインスタンスを作成し、APIを登録・テストできる
自組織でのAPI管理導入を検討できる

※本記事は、Azure Portalの基本的な操作経験と、REST APIの基本的な理解があることを前提としています。

用語集
API管理の課題とAPIMの役割
- API管理の課題
- APIMの主なメリット
APIMの主要機能
APIMの基本アーキテクチャ
- 製品（Product）・API・操作の階層構造
- サブスクリプションキーの仕組み
実装手順
この記事で学んだこと
次回予告

用語集

本記事で使用する主要な用語を以下にまとめます。

用語	説明
APIM	Azure API Managementの略称。Azureが提供するAPI管理サービス
APIゲートウェイ	すべてのAPIリクエストを受け付ける入口。認証、ルーティング、レート制限などを処理
開発者ポータル	API利用者向けに自動生成されるセルフサービスポータル。ドキュメント閲覧やAPIテストが可能
管理ポータル	API提供者が使用する管理画面。Azure Portal上でAPIの設定や監視を実施
製品（Product）	1つ以上のAPIをまとめたパッケージ。利用規約やアクセスレベルを定義
操作（Operation）	個別のAPIエンドポイント。HTTPメソッドとURLパスの組み合わせ（例：`GET /users`）
サブスクリプションキー	APIへのアクセスを制御するための認証キー。主キーと副キーの2種類で構成
ポリシー	APIの動作を制御するルール。認証、変換、レート制限などを設定
レート制限	一定期間内のAPI呼び出し回数を制限する機能。バックエンド保護に利用
クォータ	サブスクリプションごとに設定する呼び出し回数やデータ転送量の上限
バックエンドサービス	APIMの背後にある実際のAPIやマイクロサービス（例：Azure Functions、App Service）
SLA	Service Level Agreement（サービスレベル契約）。サービスの可用性保証
OpenAPI	API仕様を記述する標準フォーマット。ドキュメントの自動生成に利用

API管理の課題とAPIMの役割

このセクションでは、以下を学びます。

API管理における一般的な課題を理解する
APIMがどのようにそれらの課題を解決するかを学ぶ
自組織の状況と照らし合わせて考える

APIを公開・運用する際、多くの組織が共通の課題に直面します。APIMは、これらの課題を統合的に解決するサービスです。

API管理の課題

以下の表は、よくあるAPI管理の課題と、APIMがどのように解決するかをマッピングしたものです。

課題カテゴリ	具体的な課題	APIMによる解決策
セキュリティ	誰がAPIにアクセスしているか把握できない	統一されたゲートウェイですべてのアクセスを一元管理し、利用者を可視化
セキュリティ	認証・認可の仕組みを個別に実装する必要がある	組み込みのセキュリティ機能で認証・認可・アクセス制御を標準提供
セキュリティ	APIキーの管理が煩雑になる	サブスクリプションキー管理機能で主キー・副キーを簡単に管理、ローテーション可能
運用	過度なリクエストでバックエンドサービスが圧迫される	トラフィック制御機能でレート制限、クォータ、キャッシングを設定し安定運用
運用	API利用状況の監視が難しい	分析・モニタリング機能でAPI利用状況をリアルタイムで可視化
運用	複数のAPIバージョンを同時に管理する必要がある	バージョン管理機能で複数バージョンの並行運用とスムーズな移行をサポート
開発者体験	API利用者向けのドキュメントを別途作成・管理する必要がある	開発者ポータルでAPIドキュメントを自動生成、常に最新の状態を維持
開発者体験	APIの試用環境を提供するのが困難	インタラクティブなテストコンソールをポータル上で提供、すぐに試用可能
開発者体験	API利用申請のプロセスが煩雑	セルフサービスポータルでAPIキー取得から利用開始までを自動化

APIMの主なメリット

開発チームは横断的関心事（認証、ログなど）の実装から解放される
運用チームはAPI全体を統一的に監視・管理できる
API利用者は使いやすいポータルで迅速に開発を開始できる

APIMの主要機能

このセクションでは、以下を学びます。

APIMを構成する4つの主要機能を理解する
各機能が果たす役割を把握する
API管理の全体像をイメージする

1. APIゲートウェイ

APIMは、あらゆる場所にあるバックエンドサービス（Azure Functions、App Service、オンプレミスのサービス、外部APIなど）の前面に配置され、APIゲートウェイとして機能します。すべてのAPIリクエストを受け付ける入口です。

主な役割は以下です。

APIキーやJWTトークンの検証
レート制限とクォータの適用
リクエスト/レスポンスの変換
バックエンドサービスへのルーティング

クライアント-APIM-バックエンドの構成図 — 図1: APIMゲートウェイの基本構成

2. 開発者ポータル

API利用者向けのセルフサービスポータルです。

以下の機能が提供されます。

APIドキュメントの自動生成
インタラクティブなAPIテストコンソール
APIキーの取得・管理
利用状況の確認

開発者ポータルは、APIMインスタンスを作成すると自動的に生成されます。デザインのカスタマイズも可能です（詳細は今後の記事で解説予定）。

開発者ポータルの詳細な機能や管理方法については、次回の応用編で詳しく紹介します。

3. 管理ポータル（Azure Portal）

API提供者が使用する管理画面です。

以下の操作が可能です。

APIの登録と設定
ポリシーの定義
製品とサブスクリプションの管理
ユーザーとグループの管理
分析データの確認

APIMの管理ポータル画面 — 図3: Azure Portal上のAPIM管理画面

4. 分析とモニタリング

API利用状況をリアルタイムで可視化します。

確認できる情報は以下です。

API呼び出し回数
レスポンスタイム
エラー率
地理的な利用分布
利用者ごとの統計

APIMの基本アーキテクチャ

このセクションでは、以下を学びます。

製品・API・操作の階層構造を理解する
サブスクリプションキーの仕組みを学ぶ
APIアクセス制御の基本を把握する

APIMでは、APIを階層構造で管理します。この構造を理解することが、効果的な運用の第一歩です。

製品（Product）・API・操作の階層構造

製品（Product）
  └── API
       └── 操作（Operation）

製品（Product）

1つ以上のAPIをまとめたパッケージ
利用規約、レート制限、サブスクリプションキーの単位
例：「Starter」「Professional」「Enterprise」

API

バックエンドサービスのエンドポイント群
複数の操作（Operation）で構成
例：「User API」「Order API」

操作（Operation）

個別のAPIエンドポイント
HTTPメソッドとURLパスの組み合わせ
例：GET /users/{id}、POST /orders

サブスクリプションキーの仕組み

APIMでは、サブスクリプションキーを使ってAPIへのアクセスを制御します。

サブスクリプションの種類

製品スコープ: 特定の製品内のすべてのAPIにアクセス可能
APIスコープ: 特定のAPI内のすべての操作にアクセス可能
全スコープ: APIMインスタンス内のすべてのAPIにアクセス可能（推奨しません）

キーの構成

Primary Key（主キー）
Secondary Key（副キー）

2つのキーを使い分けることで、ダウンタイムなしでキーのローテーションが可能です（詳細は今後の記事で解説予定）。

API呼び出し時の使用方法

HTTPヘッダーまたはクエリパラメータでキーを送信します。

# ヘッダーで送信（推奨）
GET https://<your-apim-instance>.azure-api.net/api/users
Ocp-Apim-Subscription-Key: your-subscription-key

# クエリパラメータで送信
GET https://<your-apim-instance>.azure-api.net/api/users?subscription-key=your-subscription-key

ベストプラクティス

ヘッダーでの送信を推奨: URLにキーが表示されないため、セキュリティ上安全です
定期的なキーローテーション: セキュリティ強化のため、主キーと副キーを交互に使用しましょう
スコープの適切な設定: 必要最小限のアクセス権限を付与しましょう

実装手順

このセクションでは、以下を実施します。

APIMインスタンスを実際に作成する
サンプルAPIを登録して動作を確認する
APIテストの基本手順を体験する

それでは、実際にAzure Portal上でAPIMインスタンスを作成してみましょう。

APIMインスタンスを作成する

Azure Portalで「API Management」を検索し、「+ 作成」をクリックします。

APIM作成画面（検索） — 図5: Azure PortalでのAPIM検索画面

以下の設定を入力してください。

項目	設定値（例）	説明
リソースグループ	`rg-apim-demo`	新規作成または既存を選択
リージョン	`Japan East`	APIMをデプロイする地域
リソース名	`apim-demo-yourname`	グローバルで一意な名前（`[名前].azure-api.net`となる）
組織名	`Contoso`	開発者ポータルに表示される名前
管理者のメール	`admin@contoso.com`	システム通知の送信先
価格レベル	`Developer (SLA なし)`	開発・テスト用（本番は`Basic`以上を選択）

「確認および作成」→「作成」をクリックします。

所要時間: APIMインスタンスの作成には通常30〜45分かかります☕

デプロイ完了後、「リソースに移動」をクリックして管理画面に進みます。

最初のAPIを登録する

今回は、サンプルとして投稿情報を返すシンプルなAPIを登録します。

サンプルAPIについて

今回は、JSONPlaceholderという無料のテスト用REST APIを登録して使用します。

今回使用するエンドポイントは以下通りです。

ベースURL: https://jsonplaceholder.typicode.com
エンドポイント: GET /posts/1
機能: 投稿情報を返す

手順1: OpenAPI仕様ファイルを準備する

以下の内容をテキストエディタにコピーして、jsonplaceholder-api.jsonとして保存してください。

{
  "openapi": "3.0.0",
  "info": {
    "title": "JSONPlaceholder API",
    "description": "Sample REST API for testing and prototyping",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://jsonplaceholder.typicode.com"
    }
  ],
  "paths": {
    "/posts/1": {
      "get": {
        "summary": "Get post by ID",
        "description": "Returns a single post information",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "example": {
                  "userId": 1,
                  "id": 1,
                  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
                  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
                }
              }
            }
          }
        }
      }
    }
  }
}