エンドポイント：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": "latest trends in LLM RAG",
"maxResults": 10,
"language": "en",
"region": "US",
"maxLength": 3000,
"contentFormat": "passage"
}'
Parameters
| パラメーター | Required | タイプ | Default | Description |
|---|---|---|---|---|
| クエリ | はい | 文字列 | - | 検索クエリ文字列。 最大長は 1000 文字です。 "site:" 演算子と "-site:" 演算子をサポートし、特定のサイト (例: "query site:example.com") の結果を含めるか除外します。 これらの演算子は、本質的に結果の関連性が低下するため、必要な場合にのみ使用します。 |
| maxResults | いいえ | 整数 | 10 | 返される結果の最大数。 既定値は 10、最大値は 50 です。 |
| 言語 | いいえ | 文字列 | "en" | 検索結果のインターフェイス言語の 2 文字の ISO 639-1 言語コード。 完全な一覧については、「 サポートされている言語 」を参照してください。 |
| リージョン | いいえ | 文字列 | "US" | 結果の取得先の 2 文字の国/地域コード (例: "US"、"JP"、"GB")。 完全な一覧については、「 サポートされているリージョン 」を参照してください。 |
| 位置 | いいえ | 文字列 | - | 場所情報の形式は "lat:<float>;long:<float>", 例: "lat:40.753250;long:-74.003807" 指定しない場合、クエリ内の場所が推論されます。 |
| コンテンツフォーマット | いいえ | 文字列 | "passage" ("html" with full document access) |
passage は、クエリに最も関連する各結果の部分を返します (接地に推奨)。
textを html し、 markdown 完全なドキュメントを返し、完全なドキュメント アクセス権を持つアプリケーションにのみ適用されます。 「パッサージュとコンテンツ形式」を参照してください。 すべての要求に対して設定します。 注: Web API は、 snippet フィールドを返しません。 |
| マックスレングス | いいえ | 整数 | 3000 (完全なドキュメント アクセス権を持つ 10000) | 結果あたりの content の最大文字数は 1 ~ 5,0000 文字です。 完全なドキュメント アクセスがない場合、 content は最大 3,000 文字です。
「既定値と制限」を参照してください。 すべての要求に対して設定します。 |
| safeSearch | いいえ | 文字列 | "strict" | 安全な検索フィルター処理のレベル。 値: "off"、"strict"。 既定値は "strict" です。 |
コンテンツ形式
contentFormat
=
passageを設定して、クエリに最も関連する各結果の部分を取得します。最大maxLength文字 (3000 が適切な開始点です)。 これは接地に推奨される形式です。FAQ の 「 passageとは何か、なぜ使用するのか 」を参照してください。 完全なドキュメント アクセス権を持つアプリケーションは、 text、 html 、または markdownとしてドキュメント全体を要求することもできます。他のアプリケーションの場合、これらの形式では HTTP 403 が返されます。 「 節とコンテンツの形式」を参照してください。
セーフサーチ
SafeSearch モードを使用すると、結果が返される前に Web API が除外する機密性の高い Web コンテンツの量を制御できます。 機密性の高いコンテンツには、暴力、自傷行為、その他のカテゴリが含まれます。 既定値は、strict です。
| Value | Description | 推奨対象 |
|---|---|---|
strict |
成人向け、わいせつ、暴力、嫌悪、自傷行為のトピックに関連するコンテンツをブロックします。 | 子どもの安全な教育、消費者/保守的な展開。 |
off |
それでも、違法なコンテンツはブロックされます。 その他の有害な可能性があるコンテンツの場合は、最終的なフィルター処理の責任をユーザーに移します。 | 調査、分析、オプトイン エンタープライズ、高度な 3P ユース ケース。 |
Note
site: クエリ演算子を使用する場合、応答には、safeSearch値に関係なく成人のコンテンツが含まれる場合があります。
site:は、サイト上のコンテンツを認識していて、シナリオで成人用コンテンツの可能性がサポートされている場合にのみ使用します。
要求ヘッダー
| Field | タイプ | Description |
|---|---|---|
| ホスティング | 文字列 | Microsoft AI API のホスト: api.microsoft.ai。 |
| x-apikey または Authorization | 文字列 | 認証用の API キーまたはEntra IDアクセス トークン。 |
| コンテンツタイプ | 文字列 | 要求本文の MIME の種類。
application/json を使用してください。 |
応答
Web 応答
| Field | タイプ | Description |
|---|---|---|
| webResults | webResult の配列 | Web ページの結果の一覧。 |
| querySignals | querySignals | 検索クエリのクエリ レベルのランク付けシグナル。 |
| riskLevel | 文字列 | クエリに対して評価される安全リスク レベル。 指定できる値: low、moderate、high、veryHigh。 |
| instrumentationClickBase | 文字列 | クリック ping 要求のベース URL。 結果項目から instrumentationSuffix 値を追加して、完全な ping URL を形成します。 EnableInstrumentationPing プロファイル フラグを持つアプリケーションにのみ存在します。 注: ユーザーのクリックは、URL リダイレクトを使用してログに記録することもできます。 リダイレクトが有効になっている場合、ユーザーのクリックをログに記録するためのアクションは必要なく、 instrumentationClickBase は応答に含まれません。 セットアップ手順については、 インストルメンテーション ガイド を参照してください。 |
| instrumentationCitationBase | 文字列 | LLM ログ ping 要求のベース URL。 完全な ping URL を形成する DATA ペイロードを追加します。 EnableInstrumentationPing プロファイル フラグを持つアプリケーションにのみ存在します。 |
| traceId | 文字列 | デバッグ用のトレース ID。 |
querySignals
| Field | タイプ | Description |
|---|---|---|
| freshness | boolean | このクエリの他のドキュメントよりも新しいドキュメントの優先順位を付ける必要があるかどうかを示します。 |
webResult
| Field | タイプ | Description |
|---|---|---|
| title | 文字列 | Web ページのタイトル。 |
| url | 文字列 | Web ページのソース URL。 URL リダイレクトが有効になっている中国のユーザーの場合、このフィールドには clickUrlと同じリダイレクト URL が代わりに含まれます。 |
| ドメイン | 文字列 | 結果の宛先ホスト。 URL リダイレクトが有効になっている中国のユーザーに対してのみ返されます。 |
| コンテンツ | 文字列 | Web ページの詳細なコンテンツ (別名グラウンド)。 |
| crawledAt | 文字列 | Web ページの最後のクロール日は、ISO8601形式に従います。 |
| lastUpdatedAt | 文字列 | Web ページの最終更新日は、ISO8601形式に従います。 |
| 言語 | 文字列 | Web ページの言語では、ISO 639-1 言語コードが使用されます。 |
| isAdult | boolean | 結果に成人コンテンツが含まれるかどうかを示します。 |
| clickUrl | 文字列 | クリックをプロキシするリダイレクト URL Bing。 クリック リダイレクトが有効な場合にのみ存在します。 |
| instrumentationSuffix | 文字列 | この結果項目のインストルメンテーション ping URL ベースに追加するサフィックス。 インストルメンテーション ping URL と clickUrl リダイレクトの両方の K 値として使用されます。 インストルメンテーション ping が有効な場合に表示されます。 |
| contentTier | 文字列 | 結果のコンテンツ層。コンテンツ ソースの商用アクセス特性を記述します。 使用可能な値: standard (既定のサービスオファリングのすべての顧客が利用できる標準コンテンツ)、 entitled (顧客がパブリッシャーから直接ライセンスを取得し、独自の契約上の取り決めを通じてアクセスできる Bring Your Own License (BYOL) コンテンツを含む、既存の顧客ライセンス契約を通じて利用可能なコンテンツ)、 premium (標準オファリングを超える追加の価値を提供し、課金の対象となるプレミアム コンテンツ)。 |
Note
crawledAtフィールドとlastUpdatedAtフィールドの値は省略可能です。 つまり、カバレッジは 100%ではありません。 これらのフィールドには空の値が表示される場合があります。
エラー コード
| 状態コード | エラー カテゴリ | Description | 一般的な原因 |
|---|---|---|---|
| 200 | 成功 | 要求は成功しました。 | - |
| 400 | 正しくない要求 | 要求パラメーターが無効です。 | 必須フィールドが見つからない、無効なパラメーター値、形式が正しくない JSON |
| 401 | Unauthorized | 認証に失敗したか、見つかりません。 | 無効な API キー、x-apikey ヘッダーがありません |
| 403 | 許可されていません | 有効な資格情報ですが、アクセス許可が不十分です。 | API キーに必要なアクセス許可がない |
| 410 | 使用されていないリソース (Gone) | HTTPS が必要です。 | HTTPS ではなく HTTP 経由で行われた要求 |
| 415 | サポートされていないメディアの種類 | コンテンツ タイプはサポートされていません。 | コンテンツ タイプ ヘッダーが見つからないか、正しくない |
| 429 | 要求が多すぎます | レート制限を超えました。 | 時間枠内の要求が多すぎます |
| 500 | サーバー内部エラー | 予期しないサーバー エラー。 | 一時的なサーバーの問題 |
| 503 | サービス利用不可 | サービスは一時的に使用できません。 | メンテナンスまたは一時的な停止 |
| 504 | ゲートウェイのタイムアウト | リクエストがタイムアウトしました。 | アップストリーム サービスのタイムアウト |
エラー処理のガイダンスの詳細については、「 エラー処理」を参照してください。