Azure API Management で Azure Event Hubs にイベントを記録する方法
適用対象: すべての API Management レベル
この記事では、Azure Event Hubs を使用して API Management のログを記録する方法について説明します。
Azure Event Hubs は、1 秒間に数百万件のイベントを取り込むことができる高度にスケーラブルなデータ受信サービスであり、接続されたデバイスとアプリケーションで生成される大量のデータを処理および分析できます。 Event Hubs はイベント パイプラインの「玄関」として機能し、Event Hubs に収集されたデータは、任意のリアルタイム分析プロバイダーまたはバッチ処理/ストレージ アダプターを使用して変換および格納できます。 Event Hubs はイベント ストリームの生成とイベントの使用を分離し、イベント コンシューマーが独自のスケジュールでイベントにアクセスできるようにします。
Note
現在、この機能はワークスペースでは使用できません。
前提条件
- API Management サービス インスタンス。 持っていない場合は、API Management サービスのインスタンスの作成に関する記事をご覧ください。
- Azure Event Hubs 名前空間とイベント ハブ。 詳細な手順については、「Azure portal を使用して Event Hubs 名前空間とイベント ハブを作成する」を参照してください。
注意
Event Hubs リソースは、API Management リソースとは別のサブスクリプション、さらには別のテナントに置いても構いません
イベント ハブへのアクセスを構成する
イベント ハブにイベントを記録するには、API Management からアクセスするための資格情報を構成する必要があります。 API Management では、次の 2 つのアクセス機構のいずれかをサポートします。
- API Management インスタンスのマネージド ID (推奨)
- Event Hubs の接続文字列
Note
可能であれば、セキュリティ強化のためにマネージド ID 資格情報を使用することをお勧めします。
オプション 1: API Management マネージド ID を構成する
API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てた API Management 用のマネージド ID を有効にします。
- ユーザー割り当てマネージド ID を有効にする場合は、ID のクライアント ID をメモします。
Azure Event Hubs データ送信者ロールを ID に割り当て、そのスコープを Event Hubs 名前空間、またはログ記録に使用するイベント ハブに設定します。 ロールは、Azure portal または他の Azure ツールを使用して割り当てることができます。
オプション 2: Event Hubs の接続文字列を構成する
Event Hubs 接続文字列を作成するには、「Event Hubs の接続文字列の取得」を参照してください。
- 接続文字列は、Event Hubs 名前空間、または API Management からのログ記録に使用する特定のイベント ハブに使用できます。
- 接続文字列の共有アクセス ポリシーでは、少なくとも送信アクセス許可を有効にする必要があります。
API Management ロガーの作成
次の手順は、イベント ハブにイベントを記録できるように、API Management サービスでロガーを構成します。
API Management REST API を直接使用するか、Azure PowerShell、Bicep テンプレート、Azure Resource Management テンプレートなどのツールを使用して、API Management ロガーを作成および管理します。
オプション 1: マネージド ID 資格情報を使用するロガー (推奨)
システム割り当て、またはユーザー割り当てのマネージド ID 資格情報を使用して、イベント ハブに対して API Management ロガーを構成できます。
システム割り当てマネージド ID の資格情報を持つロガー
前提条件については、「API Management マネージド ID を構成する」を参照してください。
次の要求本文で API Management Logger - Create または Update REST API を使用します。
{
"properties": {
"loggerType": "azureEventHub",
"description": "Event Hub logger with system-assigned managed identity",
"credentials": {
"endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
"identityClientId":"SystemAssigned",
"name":"<EventHubName>"
}
}
}
ユーザー割り当てマネージド ID の資格情報を持つロガー
前提条件については、「API Management マネージド ID を構成する」を参照してください。
次の要求本文で API Management Logger - Create または Update REST API を使用します。
{
"properties": {
"loggerType": "azureEventHub",
"description": "Event Hub logger with user-assigned managed identity",
"credentials": {
"endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
"identityClientId":"<ClientID>",
"name":"<EventHubName>"
}
}
}
オプション 2. 接続文字列の資格情報を持つロガー
前提条件については、「Event Hubs の接続文字列を構成する」を参照してください。
Note
可能であれば、マネージド ID 資格情報を使用するロガーを構成することをお勧めします。 この記事の「マネージド ID 資格情報を使用するロガーを構成する」を参照してください。
次の例では、New-AzApiManagementLogger コマンドレットを使用し、接続文字列を構成してイベント ハブへのロガーを作成します。
# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"
# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"
log-to-eventhub ポリシーを構成する
API Management でロガーを構成したら、目的のイベントを記録するように log-to-eventhub ポリシーを構成できます。 たとえば、要求をログに記録するには log-to-eventhub
ポリシーを受信ポリシー セクションで使用し、応答をログに記録するには送信ポリシー セクションで使用します。
API Management インスタンスに移動します。
[APIs] (API) を選択し、ポリシーを追加する API を選択します。 この例では、全製品 ( [無制限] ) の [Echo API] にポリシーを追加しています。
[すべての操作] を選択します。
画面の上部の [設計] タブを選択します。
[Inbound processing] (受信処理) または [Outbound processing] (送信処理) ウィンドウで、
</>
(コード エディター) アイコンを選択します。 詳細については、ポリシーの設定または編集方法に関する記事をご覧ください。inbound
またはoutbound
ポリシー セクションにカーソルを置きます。右側のウィンドウで、 [詳細なポリシー]>[Log to EventHub](EventHub へのログ記録) を選択します。 これにより、
log-to-eventhub
ポリシー ステートメント テンプレートが挿入されます。<log-to-eventhub logger-id="logger-id"> @{ return new JObject( new JProperty("EventTime", DateTime.UtcNow.ToString()), new JProperty("ServiceName", context.Deployment.ServiceName), new JProperty("RequestId", context.RequestId), new JProperty("RequestIp", context.Request.IpAddress), new JProperty("OperationName", context.Operation.Name) ).ToString(); } </log-to-eventhub>
logger-id
は、前のステップで作成したロガーの名前に置き換えてください。log-to-eventhub
要素の値は、文字列を返す式であれば何でもかまいません。 この例では、日付と時刻、サービス名、要求 ID、要求の IP アドレス、操作の名前を含む JSON 形式の文字列がログされます。
[保存] を選択して、更新したポリシー構成を保存します。 保存するとすぐにポリシーが有効になり、指定したイベント ハブにイベントが記録されます。
Note
この API Management ポリシーからイベント ハブに送信できる最大メッセージ サイズは 200 キロバイト (KB) です。 イベント ハブに送信されたメッセージが 200 KB より大きい場合は、自動的に切り詰められ、切り詰められたメッセージがイベント ハブに転送されます。 メッセージが大きい場合は、200 KB の制限を回避するための回避策として、Azure API Management で Azure Storage を使用することを検討してください。 詳細については、この記事をご覧ください。
Azure Stream Analytics を使用して Event Hubs 内のログをプレビューする
Azure Stream Analytics のクエリを使用して、Event Hubs 内のログをプレビューすることができます。
- Azure portal で、ロガーがイベントを送信するイベント ハブを参照します。
- [機能] で、 [データの処理] タブを選択します。
- [イベントからのリアルタイムの分析情報を有効にする] カードで [開始する] を選択します。
- [入力のプレビュー] タブでログをプレビューできます。表示されたデータが最新でない場合は、 [更新] を選択して最新のイベントを表示します。
次のステップ
- Azure Event Hubs の詳細
- API Management と Event Hubs の統合の詳細
- ロガーのエンティティ リファレンス
- log-to-eventhub ポリシー リファレンス
- Azure Application Insights との統合について学習する