Azure Time Series Insights API の認証と承認

[アーティクル]
10/25/2023

Note

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

ビジネスニーズによっては、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 トークン] をオンにすることによって、暗黙的な許可のフローを有効にします。
[構成]、[保存] の順にクリックします。
Microsoft Entra アプリの Azure Time Series Insights を関連付けます。 [API のアクセス許可]>[アクセス許可の追加]>[所属する組織で使用している API] を選択します。

検索バーに「Azure Time Series Insights」と入力した後、Azure Time Series Insights を選択します。
次に、お使いのアプリで必要な 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;

アプリの登録

Microsoft Authentication Library (MSAL) を使用して、アプリ登録用のトークンを取得します。

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

次のステップ

Gen1 Azure Time Series Insights API を呼び出すサンプルコードについては、C# を使用した Gen1 データの照会に関する記事を参照してください。
Gen2 Azure Time Series Insights API のコードサンプルを呼び出すサンプルコードについては、C# を使用した Gen2 データの照会に関する記事を参照してください。
API リファレンスについては、クエリ API リファレンスのドキュメントを参照してください。

Azure Time Series Insights API の認証と承認

マネージド ID

Microsoft Entra アプリの登録

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

マネージド ID

アプリケーションの登録

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

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

マネージド ID

アプリの登録

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

HTTP ヘッダー

HTTP パラメーター

次のステップ

その他のリソース