Git を使用して API Management サービス構成を保存および構成する方法

各 API Management サービス インスタンスは、サービス インスタンスの構成とメタデータに関する情報が格納されている構成データベースを保持します。 サービス インスタンスへの変更は、Azure Portal の設定変更、Azure PowerShellやAzure CLI、または REST API 呼び出しのようなAzureツールの使用によって行うことができます。 これらのメソッドのほか、Git を使用してサービス インスタンスの構成を管理することもできます。Git を使用すると、次のようなシナリオが可能になります:

  • 構成のバージョン管理 - サービス構成のさまざまなバージョンをダウンロードして保存する
  • 構成の一括変更 - ローカル リポジトリ内のサービス構成の複数の部分を変更し、1 回の操作で変更をサーバーに返して統合する
  • 慣れ親しんだ Git のツールチェーンとワークフロー - 既に使い慣れた Git ツーリングとワークフローを使用する

次の図は、API Management サービス インスタンスを構成するためのさまざまな方法の概要を示しています。

Azure API Managementを構成する方法の比較を表す表。

Azure Portal、Azureツール、PowerShellまたはAzure CLIまたはREST API を使用してサービスに変更を加える場合は、図の右側に示されているように、サービス構成データベースの管理に https://{name}.management.azure-api.net エンドポイントを使用します。 図の左側では、Git を使用してサービス構成を管理する方法を示しています。この場合、https://{name}.scm.azure-api.net にあるご利用のサービスの Git リポジトリを使用します。

Git を使用して API Management サービス インスタンスを管理する手順の概要は次のとおりです。

  1. サービスの Git 構成にアクセスする
  2. サービス構成データベースを Git リポジトリに保存する
  3. Git リポジトリをローカル コンピューターに複製する
  4. 最新のリポジトリをローカル コンピューターにプルし、変更をコミットしてリポジトリにプッシュする
  5. リポジトリからサービス構成データベースに変更をデプロイする

この記事では、Git を有効にして使用し、サービス構成を管理する方法について説明します。また、Git リポジトリ内のファイルとフォルダーに関するリファレンス情報も提供します。

重要

このフィーチャーは、エクスポートされたサイズが 10 MB 未満、エンティティ数が 10,000 未満など、小規模から中規模のAPI Management サービス構成で動作するように設計されています。 多数のエンティティ (製品、API、操作、スキーマなど) を持つサービスでは、Git コマンドをプロセスするするときに予期しない失敗が発生する可能性があります。 このような障害が発生した場合は、サービス構成のサイズを縮小して、再試行してください。 問題が生じた場合は、Azure サポートにお問い合わせください。

可用性

重要

この機能は、API Management の PremiumStandardBasicDeveloper レベルで使用できます。

サービスの Git 構成にアクセスする

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

  2. 左側のメニューの デプロイとインフラストラクチャ で、リポジトリ を選択します。

API Management用のGit構成へのアクセスの方法を示すスクリーンショット。

サービス構成を Git リポジトリに保存するには

注意事項

名前付きの値として定義されていないシークレットはすべて、リポジトリに保存され、履歴に残ります。 名前付きの値は、すべての API 構成とポリシーの定数文字列値 (シークレットなど) を管理するための安全な場所を提供します。そのため、定数文字列値をポリシー ステートメントに直接保存する必要がありません。 詳細については、「Azure API Management ポリシーで名前付きの値を使用する」を参照してください。

リポジトリを複製する前に、サービス構成の現在の状態をリポジトリに保存します。

  1. [リポジトリ]ページ で、[リポジトリ に保存] を選択します。

  2. 構成を保存するためのブランチの名前など、確認スクリーンで必要な変更を行い、[保存] を選択 します。

しばらくすると構成が保存されます。また、最後に構成を変更した日時、サービス構成とリポジトリの間で最後に行われた同期の日時など、リポジトリの構成状態が表示されます。

構成がリポジトリに保存されたら、そのリポジトリを複製できます。

REST API を使用してサービス構成を保存する方法については、テナント構成 - 保存 を参照してください。

アクセスの資格情報を取得します

リポジトリの URL に加えて、リポジトリを複製するには、ユーザー名とパスワードが必要です。

  1. [ リポジトリ ] ページで、ページの上部付近にある [アクセス資格情報 ] を選択します。

  2. [アクセス資格情報] ページで指定されたユーザー名をメモします。

  3. パスワードを生成するには、希望する有効期限の日時を 始めに[有効期限] にセットしてから、[生成] を選択ます。

重要

このパスワードを書き留めておいてください。 このページから移動すると、パスワードが再度表示されることはありません。

ローカル コンピューターにリポジトリを複製する

次の例では Git for Windows の Git Bash ツールを使用していますが、使い慣れた Git ツールも使用できます。

Git ツールを目的のフォルダーでオープンし、次のコマンドを実行して、Git リポジトリをローカル コンピューターに複製します (以下のコマンドを使用します):

git clone https://{name}.scm.azure-api.net/

メッセージが表示されたら、ユーザー名とパスワードを入力します。

エラーが発生する場合は、次の例のように、 git clone コマンドを変更してユーザー名とパスワードを含めてみてください。

git clone https://username:password@{name}.scm.azure-api.net/

それでもエラーが発生する場合は、コマンドのパスワード部分をエンコードする URL を試してください。 これを簡単に行う 1 つの方法では、Visual Studio を開き、 [イミディエイト ウィンドウ] で次のコマンドを発行します。 [イミディエイト ウィンドウ] を開くには、Visual Studio で任意のソリューションまたはプロジェクトを開き (または新しく空のコンソール アプリケーションを作成し)、 [デバッグ] メニューから [ウィンドウ][イミディエイト] の順に選択します。

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

エンコードされたパスワードをユーザー名とリポジトリの場所と共に使用して Git コマンドを作成します。

git clone https://username:url encoded password@{name}.scm.azure-api.net/

複製が完了したら、次のようなコマンドを実行して、ディレクトリをリポジトリに変更します。

cd {name}.scm.azure-api.net/

構成を既定のブランチ (master) 以外のブランチに保存した場合は、以下のブランチをチェックアウトします:

git checkout <branch_name>

リポジトリの複製が完了したら、ローカル ファイル システムのリポジトリを表示して操作できます。 詳細については、「 ローカル Git リポジトリのファイルとフォルダーの構造のリファレンス」を参照してください。

最新のサービス インスタンス構成を使用してローカル リポジトリを更新します

Azure Portal または 他のAzure ツール を使用してAPI Management サービス インスタンスに変更を加える場合、これらの変更をリポジトリに保存しておく必要があります。その後、最新の変更を使用してローカル リポジトリを更新できます。

Azure portalを使用して変更を保存するには、API Management インスタンスの [リポジトリ] タブで [リポジトリに保存] を選択します。

ローカル リポジトリの次のものを更新します:

  1. ローカル リポジトリのフォルダーにいることを確認してください。 git clone コマンドを完了した直後に、次のようなコマンドを実行して、ディレクトリをリポジトリに変更する必要があります。

    cd {name}.scm.azure-api.net/
    
  2. ローカル リポジトリのフォルダーで、次のコマンドを発行します。

    git pull
    

ローカル リポジトリからサーバー リポジトリに変更をプッシュします

ローカル リポジトリからサーバー リポジトリに変更をプッシュするには、変更をコミットした後、サーバー リポジトリにプッシュする必要があります。 変更をコミットするには、Git コマンド ツールを開き、ローカル リポジトリのディレクトリに切り替えて、次のコマンドを発行します。

git add --all
git commit -m "Description of your changes"

コミットをすべてサーバーにプッシュするには、次のコマンドを実行します。

git push

API Management サービス インスタンスにサービス構成の変更をデプロイします

ローカルの変更をコミットし、サーバー リポジトリにプッシュしたら、これらの変更を API Management サービス インスタンスにデプロイできます。

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

  2. 左側のメニューの デプロイとインフラストラクチャ で、リポジトリ>API Managementへデプロイ を選択します。

  3. [ リポジトリ構成のデプロイ ] ページで、必要な構成変更を含むブランチの名前を入力し、必要に応じて [ 削除された製品のサブスクリプションの削除] を選択します。 [保存] を選択します。

REST API を使用してこの操作を実行する方法については、 テナント構成 - デプロイを参照してください。

ローカル Git リポジトリのファイルとフォルダーの構造のリファレンス

ローカル Git リポジトリのファイルとフォルダーには、サービス インスタンスに関する構成情報が含まれています。

Item 説明
api-management ルート フォルダー サービス インスタンスの最上位の構成が含まれています
apiReleases フォルダー サービス インスタンス内の APIリリース の構成が含まれています
apis フォルダー サービス インスタンス内の API の構成が含まれています
apiVersionSets フォルダー サービス インスタンス内の API バージョンセットの構成が含まれています
backends フォルダー サービス インスタンス内のバックエンドリソースの構成が含まれています
groups フォルダー サービス インスタンス内のグループの構成が含まれています
policies フォルダー サービス インスタンス内のポリシーが含まれています
portalStyles フォルダー サービス インスタンス内の開発者ポータルのカスタマイズに関する構成が含まれています
portalTemplates フォルダー サービス インスタンス内の開発者ポータルのテンプレートに関する構成が含まれています
products フォルダー サービス インスタンス内の製品の構成が含まれています
templates フォルダー サービス インスタンス内の電子メール テンプレートの構成が含まれています

各フォルダーには 1 つ以上のファイルを含めることができ、場合によっては 1 つ以上のフォルダーも含めることができます。たとえば、各 API、製品、またはグループに 1 つのフォルダーを含めることができます。 各フォルダー内のファイルは、フォルダー名で示されるエンティティの種類に固有です。

ファイルの種類 目的
json 各エンティティの構成情報
html エンティティについての説明 (多くの場合、開発者ポータルに表示されます)
xml ポリシー ステートメント
css 開発者ポータルのカスタマイズのスタイル シート

これらのファイルは、ローカル ファイル システム上で作成、削除、編集、管理できます。また、変更は API Management サービス インスタンスにデプロイして戻すことができます。

注意

次のエンティティは、Git リポジトリに含まれないため、Git を使用して構成することはできません。

api-management ルート フォルダー

api-management ルート フォルダーには、configuration.json ファイルがあります。このファイルには、サービス インスタンスに関する最上位の情報が次の形式で含まれています。

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

最初の 4 つの設定 (RegistrationEnabledUserRegistrationTermsUserRegistrationTermsEnabledUserRegistrationTermsConsentRequired) は、 [開発者ポータル] セクションの [ID] タブにある次の設定に対応します。

ID の設定 対応する設定
RegistrationEnabled ユーザー名とパスワード ID プロバイダーの存在
UserRegistrationTerms [ユーザー サインアップの使用条件] ボックス
UserRegistrationTermsEnabled [サインアップ ページに使用条件を表示する] チェック ボックス
UserRegistrationTermsConsentRequired [同意を要求する] チェック ボックス
RequireUserSigninEnabled [匿名ユーザーをサインイン ページにリダイレクトする] チェック ボックス

次の 4 つの設定 (DelegationEnabledDelegationUrlDelegatedSubscriptionEnabledDelegationValidationKey) は、 [開発者ポータル] セクションの [委任] タブにある次の設定に対応します。

委任の設定 対応する設定
DelegationEnabled [サインインとサインアップを委任する] チェック ボックス
DelegationUrl [委任エンドポイント URL] ボックス
DelegatedSubscriptionEnabled [製品のサブスクリプションを委任する] チェック ボックス
DelegationValidationKey [検証キーを委任する] ボックス

最後の設定 $ref-policyは、サービス インスタンスのグローバル ポリシー ステートメントのファイルに対応します。

apiReleases フォルダー

この apiReleases フォルダーには、運用 API にデプロイされた各 API リリースのフォルダーが含まれており、次の項目が含まれています。

  • apiReleases\<api release Id>\configuration.json - リリース日に関する情報を含むリリースの構成。 特定のリリースの取得 操作を呼び出す予定の場合に返される情報と同じです。

apis フォルダー

apis フォルダーには、サービス インスタンス内の各 API のフォルダーがあります。API のフォルダーには次の項目が含まれます。

  • apis\<api name>\configuration.json - API の構成で、バックエンド サービス URL と操作に関する情報が含まれています。 特定のAPIの取得 操作を呼び出す予定の場合に返される情報と同じです。
  • apis\<api name>\api.description.html - REST API の API エンティティの description プロパティに対応する API の説明。
  • apis\<api name>\operations\ - フォルダーには、API での操作にマッピングする <operation name>.description.html ファイルが含まれています。 各ファイルには、API での 1 つの操作の説明が含まれています。この操作は、REST API の操作エンティティdescription プロパティに対応します。

apiVersionSets フォルダー

この apiVerionSets フォルダーには、API 用に作成された各 API バージョン セットのフォルダーが含まれており、次の項目が含まれています。

  • apiVersionSets\<api version set Id>\configuration.json - バージョン セットの構成。 これは特定のバージョンセットを取得する操作を呼び出す予定の場合に返される情報と同じです。

groups フォルダー

groups フォルダーには、サービス インスタンスで定義された各グループのフォルダーが含まれています。

  • groups\<group name>\configuration.json - グループの構成。 特定のグループの取得 操作を呼び出した場合に返される情報と同じです。
  • groups\<group name>\description.html - グループの説明で、グループ エンティティdescriptionプロパティに対応します。

policies フォルダー

policies フォルダーには、サービス インスタンスのポリシー ステートメントが含まれています。

  • policies\global.xml - サービス インスタンスのグローバル スコープで定義されたポリシー。
  • policies\apis\<api name>\ - API スコープで定義されたポリシーがある場合は、このフォルダーに含まれます。
  • policies\apis\<api name>\<operation name>\ フォルダー - 操作スコープで定義されたポリシーがある場合は、このフォルダー内の <operation name>.xmlの ファイルに含まれます。これらのファイルは、各操作のポリシー ステートメントにマッピングします。
  • policies\products\ - 製品スコープで定義されたポリシーがある場合は、このフォルダーに含まれます。このフォルダーには、各製品のポリシー ステートメントにマッピングする <product name>.xml ファイルが含まれています。

portalStyles フォルダー

portalStyles フォルダーには、非推奨の開発者ポータルのサービス インスタンスのカスタマイズに関する構成とスタイル シートが含まれています。

  • portalStyles\configuration.json - 開発者ポータルで使用されるスタイル シートの名前が含まれています
  • portalStyles\<style name>.css - 各 <style name>.css ファイルには、開発者ポータル用のスタイルが含まれています (既定では Preview.cssProduction.css)。

portalTemplates フォルダー

この portalTemplates フォルダーには、サービス インスタンスの非推奨の開発者ポータルをカスタマイズするためのテンプレートが含まれています。

  • portalTemplates\<template name>\configuration.json - テンプレートの構成。
  • portalTemplates\<template name>\<page name>.html - テンプレートの元の HTML ページと変更された HTML ページ。

products フォルダー

products フォルダーには、サービス インスタンスで定義された各製品のフォルダーが含まれています。

  • products\<product name>\configuration.json - 製品の構成。 特定の製品の取得 操作を呼び出した場合に返される情報と同じです。
  • products\<product name>\product.description.html - 製品の説明で、REST API の製品エンティティdescriptionプロパティに対応します。

テンプレート

templates フォルダーには、サービス インスタンスの 電子メール テンプレート の構成が含まれています。

  • <template name>\configuration.json - メールアドレス テンプレートの構成です。
  • <template name>\body.html - メールアドレス テンプレートの本文です。

次のステップ

サービス インスタンスの他の管理方法については、以下を参照してください。