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

  • [アーティクル]

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

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

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

前提条件

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

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

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

オプション 1: Event Hubs の接続文字列を構成する

Event Hubs 接続文字列を作成するには、「Event Hubs の接続文字列の取得」を参照してください。

  • 接続文字列は、Event Hubs 名前空間、または API Management からのログ記録に使用する特定のイベント ハブに使用できます。
  • 接続文字列の共有アクセス ポリシーでは、少なくとも送信アクセス許可を有効にする必要があります。

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

注意

API Management マネージド ID を使用したイベント ハブへのイベントのログ記録は、API Management REST API バージョン 2022-04-01-preview 以降でサポートされます。

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

    • ユーザー割り当てマネージド ID を有効にする場合は、ID のクライアント ID をメモします。

  2. Azure Event Hubs データ送信者ロールを ID に割り当て、そのスコープを Event Hubs 名前空間、またはログ記録に使用するイベント ハブに設定します。 ロールは、Azure portal または他の Azure ツールを使用して割り当てることができます。

API Management ロガーの作成

次の手順は、イベント ハブにイベントを記録できるように、API Management サービスでロガーを構成します。

API Management REST API を直接使用するか、Azure PowerShell、Bicep テンプレート、Azure Resource Management テンプレートなどのツールを使用して、API Management ロガーを作成および管理します。

接続文字列の資格情報を持つロガー

前提条件については、「Event Hubs の接続文字列を構成する」を参照してください。

次の例では、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"

システム割り当てマネージド ID の資格情報を持つロガー

前提条件については、「API Management マネージド ID を構成する」を参照してください。

API Management REST API、あるいは Bicep または ARM テンプレートを使用して、システム割り当てマネージド ID の資格情報を持つ、イベント ハブへのロガーを構成します。

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with system assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

ユーザー割り当てマネージド ID の資格情報を持つロガー

前提条件については、「API Management マネージド ID を構成する」を参照してください。

API Management REST API、あるいは Bicep または ARM テンプレートを使用して、ユーザー割り当てマネージド ID の資格情報を持つ、イベント ハブへのロガーを構成します。

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

log-to-eventhub ポリシーを構成する

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

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

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

  3. [すべての操作] を選択します。

  4. 画面の上部の [設計] タブを選択します。

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

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

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

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

Note

この API Management ポリシーからイベント ハブに送信できる最大メッセージ サイズは 200 キロバイト (KB) です。 イベント ハブに送信されたメッセージが 200 KB より大きい場合は、自動的に切り詰められ、切り詰められたメッセージがイベント ハブに転送されます。

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

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

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

次のステップ