チュートリアル: リビジョンを使用して互換性に影響しない API の変更を安全に行う

適用対象: すべての API Management レベル

API の準備が整って開発者に使用されると、その API の変更が必要になることがありますが、API の呼び出し元を混乱させないように注意する必要もあります。 また、行った変更内容を開発者に知らせると有効です。

変更を安全にモデル化してテストできるように、Azure API Management で "リビジョン" を使用して、互換性に影響しない API の変更を行います。 準備ができたら、リビジョンを最新とし、現在の API を置き換えることができます。

背景については、「バージョンとリビジョン」をご覧ください。

このチュートリアルでは、次の作業を行う方法について説明します。

• 新しいリビジョンの追加
• リビジョンに互換性に影響しない変更を加える
• リビジョンを最新にして変更ログ エントリを追加する
• 開発者ポータルを参照して、変更内容と変更ログを確認します。
• API リビジョンにアクセスする

前提条件

• Azure API Management の用語について学習します。
• 次のクイック スタートを完了すること:Azure API Management インスタンスを作成する。
• また、次のチュートリアルを完了すること: 最初の API のインポートと発行。

新しいリビジョンの追加

1. Azure portal にサインインし、API Management インスタンスに移動します。

2. 左側のメニューの [API] で、[API] を選択します。

3. API の一覧で [Demo Conference API] (または、リビジョンを追加する別の API) を選択します。

4. [リビジョン] タブを選択します。

5. [+ リビジョンの追加] を選択します。

   

   ヒント

   API のコンテキスト メニュー ( [...] ) で [リビジョンの追加] を選択することもできます。

6. 新しいリビジョンの使用目的を示す説明を入力します。

7. ［作成］ を選択します

8. これで、新しいリビジョンが作成されました。

   Note

   元の API はリビジョン 1 のままとなります。 別のリビジョンが最新にされない限り、ユーザーはこのリビジョンを呼び出し続けます。

リビジョンに互換性に影響しない変更を加える

1. API の一覧で [Demo Conference API](デモ会議 API) を選択します。

2. 画面の上部付近の[Design] (デザイン) タブを選択します。

3. リビジョン セレクター (デザイン タブのすぐ上) に、現在の選択対象としてリビジョン 2 が表示されます。

   ヒント

   リビジョン セレクターを使用して、作業対象のリビジョンに切り替えます。

4. [+ Add Operation] (+ 操作の追加) を選択します。

5. 新しい操作を POST に設定し、操作の表示名、名前、および URL を test に設定します。

6. 新しい操作を保存します。

   

7. これで、リビジョン 2 への変更が完了しました。 ページの上部付近にあるリビジョン セレクターを使用して、リビジョン 1 に切り替えます。

8. 新しい操作はリビジョン 1 には表示さません。

リビジョンを最新にして変更ログ エントリを追加する

ポータル

1. ページの上部付近にあるメニューから [リビジョン] タブを選択します。

2. リビジョン 2 のコンテキスト メニュー (...) を開きます。

3. [これを最新とする] を選択します。

4. この変更に関するメモを投稿する場合は、 [Post to Public Change log for this API](この API のパブリック変更ログを投稿する) チェック ボックスをオンにします。 開発者が参照できるように、変更内容の説明を入力します。たとえば、「テスト用リビジョン。新しい "test" 操作を追加しました。」と入力します。

5. これでリビジョン 2 が最新となりました。

   

Azure CLI

Azure CLI の使用を開始するには:

• Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

  

• CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

  • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

  • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

  • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

リリースを作成および更新するには、次の手順に従います。

1. az apim api list コマンドを実行して、API ID を表示します。

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   次のコマンドで使用する API ID は Name 値です。 API リビジョンは ApiRevision 列にあります。

2. リリース ノートと共にリリースを作成するには、az apim api release create コマンドを実行します。

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   リリースしたリビジョンが最新のリビジョンになります。

3. リリースを表示するには、az apim api release list コマンドを使用します。

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   指定したメモは変更ログに表示されます。 これらは前のコマンドの出力で確認できます。

4. リリースを作成するときに、--notes パラメーターは省略可能です。 メモは、az apim api release update コマンドを使用して後で追加または変更できます。

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   リリース ID の Name 列の値を使用します。

リリースを削除するには、az apim api release delete コマンドを実行します。

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

開発者ポータルを参照して、変更内容と変更ログを確認します。

開発者ポータルを試したことがあれば、そこで API の変更と変更ログを確認できます。

1. Azure portal で、API Management インスタンスに移動します。
2. 左側のメニューの [API] で、[API] を選択します。
3. 上部のメニューから [開発者ポータル] を選択します。
4. 開発者ポータルで、 [API] を選択し、 [Demo Conference API] を選択します。
5. 新しい test 操作が使用可能となっています。
6. API 名の近くにある [変更ログ] を選択します。
7. この一覧に、変更ログ エントリが表示されます。

API リビジョンにアクセスする

API の各リビジョンには、特別な形式の URL を使用してアクセスできます。 対象の API の URL パスの末尾に (ただしクエリ文字列の前に) ;rev={revisionNumber} を追加することで、その API の特定のリビジョンにアクセスします。 たとえば、次の URL を使用すると、Demo Conference API のリビジョン 2 にアクセスできます。

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

API のリビジョンの URL パスは、Azure portal の [リビジョン] タブで確認できます。

ヒント

API パスに ;rev={revisionNumber} を追加する完全な URL に加えて、;rev 文字列のない API パスを使用して、API の "現在" のリビジョンにアクセスできます。

まとめ

このチュートリアルでは、次の作業を行う方法を学びました。

• 新しいリビジョンの追加
• リビジョンに互換性に影響しない変更を加える
• リビジョンを最新にして変更ログ エントリを追加する
• 開発者ポータルを参照して、変更内容と変更ログを確認します。
• API リビジョンにアクセスする

次のステップ

次のチュートリアルに進みます。

API の複数のバージョンを発行する