次の方法で共有

Azure Time Series Insights API の認証と承認

  • [アーティクル]

Note

Time Series Insights サービスは、2024 年 7 月 7 日に廃止されます。 できるだけ早く既存の環境を代替ソリューションに移行することを検討してください。 サポートの終了と移行の詳細については、こちらのドキュメントを参照してください。

ビジネス ニーズによっては、Azure Time Series Insights 環境の API と対話するために使用する 1 つ以上のクライアント アプリケーションが、ソリューションに含まれる場合があります。 Azure Time Series Insights により、OAUTH 2.0 に基づく Microsoft Entra セキュリティ トークンを使用して認証が実行されます。 クライアントの認証を行うには、適切なアクセス許可を持つベアラー トークンを取得し、API の呼び出しでそれを渡す必要があります。 このドキュメントでは、ベアラー トークンを取得して認証を行うために使用できる、資格情報を取得するためのいくつかの方法について説明します。これには、マネージド ID の使用と Microsoft Entra アプリの登録が含まれます。

マネージド ID

以下のセクションでは、Microsoft Entra ID からのマネージド ID を使用して、Azure Time Series Insights API にアクセスする方法について説明します。 Azure のマネージド ID を使用すれば、開発者が資格情報を管理する必要がなくなります。Azure リソースの ID は Microsoft Entra ID から提供され、その ID を使用して Microsoft Entra トークンが取得されます。 以下に、マネージド ID を使用する利点をいくつか紹介します。

  • 資格情報を自ら管理する必要がない。 資格情報には、自分もアクセスできません。
  • マネージド ID を使用すると、Microsoft Entra 認証をサポートするあらゆる Azure サービス (Azure Key Vault を含む) に対して認証を行うことができます。
  • マネージド ID の使用に関して追加コストは一切かからない。

2 種類のマネージド ID の詳細については、「Azure リソースのマネージド ID とは」を参照してください

次の場所のマネージド ID を使用できます。

  • Azure VM
  • Azure App Service
  • Azure Functions
  • Azure Container Instances
  • その他...

完全な一覧については、「Azure リソースのマネージド ID をサポートする Azure サービス」を参照してください。

Microsoft Entra アプリの登録

資格情報を管理する必要がないように、可能な限りマネージド ID を使用することをお勧めします。 マネージド ID をサポートする Azure サービスでクライアント アプリケーションがホストされていない場合は、アプリケーションを Microsoft Entra テナントに登録できます。 アプリケーションを Microsoft Entra ID に登録するとき、アプリケーションの ID 構成を作成します。これによって Microsoft Entra ID との統合が可能になります。 Azure portal でアプリを登録するときに、それがシングル テナント (自分のテナント内でのみアクセス可能) かマルチテナント (他のテナント内でアクセス可能) かを選択し、必要に応じてリダイレクト URI (アクセス トークンの送信先) を設定します。

アプリの登録が完了すると、ホーム テナントまたはディレクトリ内に存在するアプリ (アプリケーション オブジェクト) のグローバルに一意なインスタンスが作成されます。 また、アプリにグローバルに一意な ID (アプリまたはクライアント ID) も割り当てられます。 ポータルでは、シークレットまたは証明書とスコープを追加してアプリを機能させることや、サインイン ダイアログでアプリのブランドをカスタマイズすることなどができます。

ポータルでアプリケーションを登録すると、ホーム テナントにアプリケーション オブジェクトとサービス プリンシパル オブジェクトが自動的に作成されます。 Microsoft Graph API を使用してアプリケーションを登録または作成する場合、サービス プリンシパル オブジェクトの作成は別の手順です。 トークンを要求するには、サービス プリンシパル オブジェクトが必要です。

お使いのアプリケーションの「セキュリティ」チェックリストを必ず確認してください。 ベスト プラクティスとしては、パスワードの資格情報 (クライアント シークレット) ではなく、証明書の資格情報を使用する必要があります。

詳細については、Microsoft Entra ID プラットフォームのアプリケーションとサービス プリンシパルのオブジェクトに関するページを参照してください。

ステップ 1: マネージド ID またはアプリの登録を作成する

マネージド ID とアプリの登録のどちらを使用するかを決定したら、次のステップとしてそれをプロビジョニングします。

マネージド ID

マネージド ID の作成に使用する手順は、コードが配置される場所と、システム割り当てまたはユーザー割り当ての ID を作成するかどうかによって異なります。 違いを理解するには、「マネージド ID の種類」を参照してください。 ID の種類を選択したら、Microsoft Entra のマネージド ID に関するドキュメントで、正しいチュートリアルを見つけてそれに従います。 そこでは、次のものに関するマネージド ID の構成方法が説明されています。

アプリケーションの登録

「アプリケーションを登録する」で示されている手順のようにします。

  • [プラットフォームの構成] 設定の手順 4 で適切なプラットフォームを選択したら、ユーザー インターフェイスの右側のサイド パネルで [リダイレクト URI] と [アクセス トークン] を構成します。

    • [リダイレクト URI] は、認証要求で指定されたアドレスと一致する必要があります。

      • ローカル開発環境でホストされているアプリでは、[パブリック クライアント (モバイルとデスクトップ)] を選択します。 [パブリック クライアント] は必ず [はい] に設定してください。
      • Azure App Service でホストされているシングルページ アプリでは、[Web] を選択します。

    • [ログアウト URL] が適切かどうかを確認します。

    • [アクセス トークン] または [ID トークン] をオンにすることによって、暗黙的な許可のフローを有効にします。

    リダイレクト URI を作成する

    [構成]、[保存] の順にクリックします。

  • Microsoft Entra アプリの Azure Time Series Insights を関連付けます。 [API のアクセス許可]>[アクセス許可の追加]>[所属する組織で使用している API] を選択します。

    API を Microsoft Entra アプリに関連付ける

    検索バーに「Azure Time Series Insights」と入力した後、Azure Time Series Insights を選択します。

  • 次に、お使いのアプリで必要な API のアクセス許可の種類を指定します。 既定では、[委任されたアクセス許可] が強調表示されます。 アクセス許可の種類を選択した後、[アクセス許可の追加] を選択します。

    お使いのアプリで必要な API のアクセス許可の種類を指定する

  • アプリケーションから環境の API をそのまま呼び出す場合は、資格情報を追加します。 資格情報により、アプリケーションはそれ自体として認証され、実行時にユーザーによる操作は必要ありません。

ステップ 2: アクセス権を付与する

Azure Time Series Insights 環境によって要求が受信されると、最初に呼び出し元のベアラー トークンが検証されます。 検証に合格すると、呼び出し元は認証され、次に要求されたアクションの実行を呼び出し元が承認されていることを確認するための別のチェックが行われます。 ユーザーまたはサービス プリンシパルを承認するには、最初に、閲覧者ロールまたは共同作成者ロールをそれらに割り当てることによって、環境へのアクセスを許可する必要があります。

  • Azure portal の UI を使用してアクセスを許可するには、記事「環境へのデータ アクセスの許可」に記載されている手順に従います。 ユーザーを選択するときは、名前または ID でマネージド ID またはアプリの登録を検索できます。

  • Azure CLI を使用してアクセスを許可するには、次のコマンドを実行します。 アクセスの管理に使用できるコマンドの完全な一覧については、こちらのドキュメントを参照してください。

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

Note

Azure CLI の timeseriesinsights 拡張機能には、バージョン 2.11.0 以降が必要です。 この拡張機能は、az tsi access-policy コマンドを初めて実行したときに自動的にインストールされます。 拡張機能の詳細をご覧ください。

ステップ 3: トークンを要求する

マネージド ID またはアプリの登録がプロビジョニングされ、ロールが割り当てられたら、それを使用して OAuth 2.0 ベアラー トークンの要求を始めることができます。 トークンの取得に使用する方法は、コードがホストされている場所と選択した言語によって異なります。 リソース (トークンの "対象ユーザー" とも呼ばれます) を指定するときは、URL または GUID によって Azure Time Series Insights を識別できます。

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

重要

リソース ID として URL を使用する場合は、トークンが https://api.timeseries.azure.com/ に正確に発行されるようにする必要があります。 末尾にスラッシュが必要です。

  • したがって、Postman を使用する場合は、AuthURL は次のようになります: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ は有効ですが、https://api.timeseries.azure.com は有効ではありません。

マネージド ID

Azure App Service または Functions からアクセスする場合は、「Azure リソースのトークンを取得する」のガイダンスに従ってください。

.NET のアプリケーションと関数の場合、マネージド ID を利用する最も簡単な方法は、.NET 用の Azure ID クライアント ライブラリを使用することです。 このクライアント ライブラリは、簡単でセキュリティ上の利点があるため、よく使われています。 開発者はコードを 1 回だけ記述すればよく、後はクライアント ライブラリにより、アプリケーションの環境 (開発者のアカウントを使用する開発者ワークステーション上か、またはマネージド サービス ID を使用して Azure にデプロイされるか) に基づいて、認証方法が決定されます。 前の AppAuthentication ライブラリからの移行に関するガイダンスについては、「AppAuthentication から Azure.Identity への移行ガイダンス」を参照してください。

C# と .NET 用 Azure ID クライアント ライブラリを使用して、Azure Time Series Insights 用のトークンを要求します。

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

アプリの登録

MSAL は、次のものを初めとする多くのアプリケーション シナリオで使用できます。

アプリの登録としてトークンを取得し、Gen2 環境からデータを照会する方法を示す C# コードのサンプルについては、GitHub のサンプル アプリを参照してください

重要

Azure Active Directory 認証ライブラリ (ADAL) を使用している場合は、MSAL に移行します。

一般的なヘッダーとパラメーター

このセクションでは、Azure Time Series Insights GA 1 API や GA2 API に対するクエリの作成に使用される、一般的な HTTP 要求ヘッダーとパラメーターについて説明します。 API 固有の要件は、Azure Time Series Insights REST API リファレンス ドキュメントに詳しく記載されています。

ヒント

REST API の使用方法、HTTP 要求の作成方法、および HTTP 応答の処理方法の詳細については、Azure REST API リファレンス を参照してください。

HTTP ヘッダー

必要な要求ヘッダーを以下に示します。

必要な要求ヘッダー 説明
承認 Azure Time Series Insights で認証を行うには、有効な OAuth 2.0 ベアラー トークンを Authorization ヘッダー内で渡す必要があります。

ヒント

チャートやグラフと共に JavaScript クライアント SDK を使用して、プログラムによって Azure Time Series Insights API で認証を行う方法については、Azure Time Series Insights のクライアント SDK のサンプルの視覚化に関する記事を参照してください。

省略可能な要求ヘッダーを以下に示します。

省略可能な要求ヘッダー 説明
Content-type application/json のみがサポートされています。
x-ms-client-request-id クライアント要求 ID。 サービスでは、この値です。 これにより、サービスでは、サービス間の操作を追跡できるようになります。
x-ms-client-session-id クライアントセッション ID。 サービスでは、この値です。 これにより、サービスでは、サービス間の関連する操作のグループを追跡できるようになります。
x-ms-client-application-name この要求を生成したアプリケーションの名前。 サービスでは、この値です。

省略可能ですが、推奨される応答ヘッダーを以下に示します。

応答ヘッダー 説明
Content-type サポートされるのは application/json のみです。
x-ms-request-id サーバーで生成された要求 ID。 要求の調査についての Microsoft への問い合わせに使用できます。
x-ms-property-not-found-behavior GA API オプションの応答ヘッダー。 指定できる値は、ThrowError (既定値) または UseNullです。

HTTP パラメーター

ヒント

必須および省略可能なクエリの情報の詳細については、参照ドキュメントを参照してください。

必須の URL クエリ文字列パラメーターは、API バージョンによって異なります。

リリース API バージョンの値
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

省略可能な URL クエリ文字列パラメーターには、HTTP 要求の実行時間のタイムアウト設定が含まれます。

省略可能なクエリパラメーター 説明 Version
timeout=<timeout> HTTP 要求実行のサーバー側のタイムアウト。 環境イベントの取得 API と環境集計の取得 API にのみ適用できます。 タイムアウト値は、"PT20S" など、ISO 8601 の期間の形式で指定され、その範囲は 1-30 s である必要があります。 既定値は 30 s。 Gen1
storeType=<storeType> ウォーム ストアが有効になっている Gen2 環境では、WarmStore または ColdStore のいずれかでクエリを実行できます。 クエリ内のこのパラメーターは、クエリを実行する必要があるストアを定義します。 定義されていない場合は、コールドストアでクエリが実行されます。 ウォームストアに対してクエリを実行するには、storeType を WarmStoreに設定する必要があります。 定義されていない場合は、コールドストアに対してクエリが実行されます。 Gen2

次のステップ