次の方法で共有

Azure API Management で Azure Event Hubs にイベントを記録する方法

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

この記事では、Azure Event Hubs を使用して API Management イベントをログに記録する方法について説明します。

Azure Event Hubs は、1 秒間に数百万件のイベントを取り込むことができる高度にスケーラブルなデータ受信サービスであり、接続されたデバイスとアプリケーションで生成される大量のデータを処理および分析できます。 Event Hubs はイベント パイプラインの "フロント ドア" として機能し、データがイベント ハブに収集された後、リアルタイム分析プロバイダーまたはバッチ処理/ストレージ アダプターを使用して変換および格納できます。 Event Hubs はイベント ストリームの生成とイベントの使用を分離し、イベント コンシューマーが独自のスケジュールでイベントにアクセスできるようにします。

注

現在、この機能はワークスペースでは使用できません。

前提条件

イベント ハブへのアクセスを構成する

イベント ハブにイベントを記録するには、API Management からアクセスするための資格情報を構成する必要があります。 API Management では、次の 2 つのアクセス機構のいずれかをサポートします。

  • API Management インスタンスのマネージド ID (推奨)
  • Event Hubs の接続文字列

注

セキュリティを強化するために、可能な場合はマネージド ID 資格情報を使用することをお勧めします。

オプション 1: API Management マネージド ID を構成する

  1. API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てた API Management 用のマネージド ID を有効にします。

    • ユーザー割り当てマネージド ID を有効にする場合は、ID の オブジェクト ID を書き留めます。

  2. 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 ロガーを作成および管理します。

システム割り当てマネージド 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 接続文字列の構成」を参照してください。

注

可能な場合は、マネージド ID 資格情報を使用してロガーを構成することをお勧めします。 この記事 の「マネージド ID 資格情報を使用してロガーを構成する」を参照してください。

次の例では、New-AzApiManagementLogger コマンドレットを使用し、接続文字列を構成してイベント ハブへのロガーを作成します。

# Details specific to API Management 
$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"

イベントハブへのログポリシーを構成する

API Management でロガーを構成した後、目的のイベントを記録するために log-to-eventhub ポリシーを構成できます。 たとえば、要求をログに記録するには log-to-eventhub ポリシーを受信ポリシー セクションで使用し、応答をログに記録するには送信ポリシー セクションで使用します。

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

  2. [API] で [API] を選択し、ポリシーを追加する API を選択します。 この例では、全製品 ( [無制限] ) の [Echo API] にポリシーを追加しています。

  3. [ デザイン ] タブで、[ すべての操作] を選択します。

  4. [ 受信処理 ] または [ 送信処理 ] ウィンドウで、 </> (ポリシー コード エディター) ボタンを選択します。 詳細については、ポリシーの設定または編集方法に関する記事をご覧ください。

  5. inbound または outbound ポリシー セクションにカーソルを置きます。

  6. タブの上部にある [スニペットの表示] を選択します。[詳細ポリシー] を選択>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>
    1. logger-id は、前のステップで作成したロガーの名前に置き換えてください。
    2. log-to-eventhub 要素の値は、文字列を返す式であれば何でもかまいません。 この例では、日付と時刻、サービス名、要求 ID、要求の IP アドレス、操作の名前を含む JSON 形式の文字列がログされます。

  7. [保存] を選択して、更新したポリシー構成を保存します。 構成が保存されるとすぐに、ポリシーがアクティブになり、イベントが指定されたイベント ハブに記録されます。

注

この API Management ポリシーからイベント ハブに送信できる最大メッセージ サイズは 200 キロバイト (KB) です。 イベント ハブに送信されるメッセージが 200 KB を超える場合は、自動的に切り捨てられ、切り捨てられたメッセージがイベント ハブに転送されます。 より大きなメッセージの場合は、200 KB の制限を回避するための回避策として、API Management で Azure Storage を使用することを検討してください。 詳細については、「 API Management から Azure Storage に要求を送信する」を参照してください。

Azure Stream Analytics を使用して Event Hubs 内のログをプレビューする

Azure Stream Analytics のクエリを使用して、Event Hubs 内のログをプレビューすることができます。

  1. Azure portal で、ロガーがイベントを送信するイベント ハブに移動します。
  2. [ 機能] で、[ データの処理] を選択します。
  3. [イベントからのリアルタイムの分析情報を有効にする] カードで [開始する] を選択します。
  4. [入力のプレビュー] タブでログをプレビューできます。表示されたデータが最新でない場合は、 [更新] を選択して最新のイベントを表示します。

関連コンテンツ

  • Last updated on