Microsoft Web IQ の使用状況を計測する

このガイドでは、Web IQ API を使用してコンテンツの使用状況をログに記録するときにテレメトリを実装する方法について説明します。

Overview

Web IQ API をインストルメント化して、応答にテレメトリ フィールドを含めることができます。これにより、アプリケーションは HTTP 要求を介してユーザー操作メトリックをログに記録できます。

サポートされているテレメトリ シナリオ:

  • LLM の使用状況: 応答を作成するときに、大規模言語モデル (LLM) が参照する検索結果をログに記録します。
  • エンド ユーザーがクリック: LLM によって要約と引用が提示された後にユーザーがクリックした引用文献をログに記録します。

インストルメンテーションの有効化

イベントをログに記録するには、Web IQ API プロファイルでインストルメンテーションを有効にする必要があります。 これを構成するには、Microsoft の担当者にお問い合わせください。

応答

インストルメンテーションを有効にすると、API 応答にはテレメトリ フィールドが含まれます。

{
  "webResults": [
    {
      "...": "...",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

フィールドの説明

Field Description
instrumentationClickBase エンド ユーザーのクリックを報告するためのベース URL。 IG (インプレッション GUID) と CID (クライアント ID) が事前に設定されています。 IDにinstrumentationSuffixを手動で追加する必要があります。
instrumentationCitationBase LLM の使用状況を報告するためのベース URL。 IGとCIDが含まれます。 Type は、"Event.ClientInst" である必要があります。 DATA は、URL でエンコードされたイベントの JSON 配列です。
instrumentationSuffix ログ記録に使用される結果ごとの一意識別子 (例: DevEx,1000)。
clickUrl リダイレクトが有効になっている場合、各結果には、エンド ユーザーを元の宛先 URL に転送するリダイレクト URL clickUrlが含まれます。 clickUrlでは、クリック イベントを手動でログに記録する必要はまったくありませんが、LLM 使用状況を手動でログに記録する必要があります。

Note

プロファイルでリダイレクトが有効になっている場合、 instrumentationClickBase は応答に含まれません。

インストルメンテーション ping と URL リダイレクトの両方が有効になっている場合の Web IQ API 応答の例を次に示します。

{
  "webResults": [
    {
      "url": "original-destination-link",
      "clickUrl": "encoded-redirection-link",
      "instrumentationSuffix": "DevEx,1000"
    }
  ],
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

実装例

依頼

エンドポイント：POST https://api.microsoft.ai/v3/search/web

サンプル要求:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "webiq",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

応答 (簡略化)

{
  "webResults": [
    {
      "title": "Microsoft Web IQ",
      "url": "https://www.microsoft.com/en-us/webiq",
      "content": "...",
      "crawledAt": "2026-06-17T22:29:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1000"
    },
    {
      "title": "WebIQ - The Web HMI System for Professional HMIs",
      "url": "https://www.smart-hmi.com/",
      "content": "...",
      "crawledAt": "2026-06-16T01:17:00.0000000Z",
      "language": "en",
      "isAdult": false,
      "instrumentationSuffix": "DevEx,1001"
    }
  ],
  "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=",
  "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=",
  "traceId": "some-trace-id"
}

テレメトリ ワークフロー

手順 1: 出典を提供する

ユーザーへの LLM 応答に引用文献を含めます。

手順 2: LLM の使用状況をログに記録する

次のフィールドを使用してオブジェクトの配列を作成します。

Field Value
T 情報のカテゴリを表すサブタイプ。 常に "CI.Info" にする必要があります
FID 機能 ID。 常に「LLM」である必要があります
Name 分類の詳細情報としてのイベント名 （e.g. 「citation」）
AppNS instrumentationSuffixのプレフィックス (例: "DevEx")
K サフィックス値 (例: "1000")

ペイロードの例:

[
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1000"
  },
  {
    "T": "CI.Info",
    "FID": "LLM",
    "Name": "citation",
    "AppNS": "DevEx",
    "K": "1001"
  }
]

配列を URL エンコードします。

var encoded_array = encodeURIComponent(JSON.stringify(data_array));

次で送信:

エンドポイント：GET https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=<encoded_array>

手順 3: ユーザーのクリックをログに記録する

ユーザーが引用をクリックしたら、次の情報を送信します。

エンドポイント：GET https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=DevEx,1001

  • 最終更新: