끝점: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 | Type | Default | Description |
|---|---|---|---|---|
| query | Yes | string | - | 검색 쿼리 문자열입니다. 최대 길이는 1000자입니다. 특정 사이트의 결과를 포함하거나 제외하도록 "site:" 및 "-site:" 연산자를 지원합니다(예: "쿼리 site:example.com"). 이러한 연산자는 본질적으로 결과 관련성을 줄이기 때문에 필요한 경우에만 사용합니다. |
| maxResults | No | integer | 10 | 반환할 최대 결과 수입니다. 기본값은 10이고 최대값은 50입니다. |
| language | No | string | "en" | 검색 결과의 인터페이스 언어에 대한 2자 ISO 639-1 언어 코드입니다. 전체 목록은 지원되는 언어 를 참조하세요. |
| region | No | string | "US" | 결과가 제공되는 위치에 대한 2자로 된 국가/지역 코드입니다(예: "US", "JP", "GB" 등). 전체 목록은 지원되는 지역을 참조하세요. |
| location | No | string | - | 위치 정보 형식 "lat:<float>; long:<float>"( 예: "lat:40.753250; long:-74.003807". 지정하지 않으면 쿼리의 위치가 유추됩니다. |
| 콘텐츠 형식 | No | string | "passage"(전체 문서 액세스 권한이 있는 "html") |
passage 는 쿼리와 가장 관련된 각 결과의 부분을 반환합니다(접지에 권장됨).
text
html 전체 문서를 반환하고 markdown 전체 문서 액세스 권한이 있는 애플리케이션에만 적용합니다. 구절 및 콘텐츠 형식을 참조하세요. 모든 요청에 대해 설정합니다. 참고: 웹 API는 필드를 반환 snippet 하지 않습니다. |
| 최대 길이 | No | integer | 3000(전체 문서 액세스 권한이 있는 10000) | 결과당 최대 문자 수 content (1~500000)입니다. 전체 문서 액세스 권한이 content 없으면 최대 3,000자입니다.
기본값 및 제한을 참조하세요. 모든 요청에 대해 설정합니다. |
| safeSearch | No | string | "strict" | 안전한 검색 필터링 수준입니다. 값: "off", "strict". 기본값은 "strict"입니다. |
콘텐츠 형식
쿼리와 가장 관련된 각 결과의 부분을 최대 문자(3,000개는 좋은 시작점)까지 가져올 수 있도록 설정합니다contentFormatpassage = .maxLength 접지에 권장되는 형식입니다. FAQ에서 passage무엇이고 왜 사용합니까? 전체 문서 액세스 권한이 있는 애플리케이션은 전체 문서를 다른 응용 프로그램의 경우 HTTP 403으로 texthtmlmarkdown요청할 수도 있습니다.
구절 및 콘텐츠 형식을 참조하세요.
SafeSearch
SafeSearch 모드를 사용하면 결과가 반환되기 전에 Web API가 필터링하는 중요한 웹 콘텐츠의 양을 제어할 수 있습니다. 중요한 콘텐츠에는 폭력, 자해 및 기타 범주가 포함됩니다. 기본값은 strict여야 합니다.
| Value | Description | 권장 대상 |
|---|---|---|
strict |
성인, 외설, 폭력, 증오 및 자해 주제와 관련된 콘텐츠를 차단합니다. | 어린이 안전, 교육, 소비자/보수적 배포. |
off |
여전히 잘못된 콘텐츠를 차단합니다. 잠재적으로 유해할 수 있는 기타 콘텐츠의 경우 최종 필터링에 대한 책임을 사용자에게 옮깁니다. | 연구, 분석, 옵트인 엔터프라이즈, 고급 3P 사용 사례. |
Note
쿼리 연산자를 site: 사용하는 경우 응답에 값에 관계없이 성인 콘텐츠가 safeSearch 포함될 수 있습니다. 사이트의 콘텐츠를 알고 있고 시나리오에서 성인 콘텐츠의 가능성을 지원하는 경우에만 사용합니다 site: .
요청 헤더
| Field | Type | Description |
|---|---|---|
| host | string | Microsoft AI API용 호스트: api.microsoft.ai. |
| x-apikey 또는 권한 부여 | string | 인증을 위한 API 키 또는 Entra ID 액세스 토큰입니다. |
| 컨텐츠 유형 (content-type) | string | 요청 본문의 MIME 형식입니다.
application/json을 사용합니다. |
응답
웹 응답
| Field | Type | Description |
|---|---|---|
| webResults | webResult 배열 | 웹 페이지 결과 목록입니다. |
| querySignals | querySignals | 검색 쿼리에 대한 쿼리 수준 순위 신호입니다. |
| riskLevel | string | 쿼리에 대해 평가된 안전 위험 수준입니다. 가능한 값: low, moderate, highveryHigh. |
| instrumentationClickBase | string | ping 요청을 클릭하기 위한 기본 URL입니다. 결과 항목의 instrumentationSuffix 값을 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. 참고: URL 리디렉션을 사용하여 사용자 클릭을 기록할 수도 있습니다. 리디렉션을 사용하도록 설정하면 사용자 클릭을 기록하는 작업이 필요하지 않으며 instrumentationClickBase 응답에 포함되지 않습니다. 설치 지침은 계측 가이드 를 참조하세요. |
| instrumentationCitationBase | string | LLM 로그 ping 요청에 대한 기본 URL입니다. 데이터 페이로드를 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. |
| traceId | string | 디버깅을 위한 추적 ID입니다. |
querySignals
| Field | Type | Description |
|---|---|---|
| freshness | 부울 | 이 쿼리의 다른 문서보다 새 문서의 우선 순위를 지정해야 하는지 여부를 나타냅니다. |
webResult
| Field | Type | Description |
|---|---|---|
| title | string | 웹 페이지의 제목입니다. |
| url | string | 웹 페이지의 원본 URL입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자의 경우 이 필드에는 .와 동일한 리디렉션 URL clickUrl이 대신 포함됩니다. |
| domain | string | 결과의 대상 호스트입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자에 대해서만 반환됩니다. |
| 콘텐츠 | string | 웹 페이지의 자세한 콘텐츠(즉, 접지)입니다. |
| crawledAt | string | 웹 페이지의 마지막 크롤링 날짜는 ISO8601 형식을 따릅니다. |
| 마지막 업데이트됨 | string | 웹 페이지의 마지막 업데이트 날짜는 ISO8601 형식을 따릅니다. |
| language | string | 웹 페이지의 언어는 ISO 639-1 언어 코드를 사용합니다. |
| isAdult | 부울 | 결과에 성인 콘텐츠가 포함되는지 여부를 나타냅니다. |
| clickUrl | string | Bing을 통해 클릭을 프록시하는 URL을 리디렉션합니다. 클릭 리디렉션을 사용하는 경우에만 존재합니다. |
| instrumentationSuffix | string | 이 결과 항목의 계측 ping URL 베이스에 추가할 접미사입니다. 계측 ping URL과 리디렉션 모두에 대한 K 값으로 clickUrl 사용됩니다. 계측 ping을 사용할 때 표시됩니다. |
| contentTier | string | 콘텐츠 원본의 상업적 액세스 특성을 설명하는 결과의 콘텐츠 계층입니다. 가능한 값: standard (기본 서비스 제공에 따라 모든 고객이 사용할 수 있는 표준 콘텐츠), entitled (고객이 게시자로부터 직접 라이선스를 부여하고 자체 계약 계약을 통해 액세스한 BYOL(Bring Your Own License) 콘텐츠를 포함하여 기존 고객 라이선스 계약을 통해 사용할 수 있는 콘텐츠), premium (표준 제공 이외의 추가 가치를 제공하고 청구가 적용되는 프리미엄 콘텐츠). |
Note
필드 값과 lastUpdatedAt 필드 값 crawledAt 은 선택 사항입니다. 즉, 해당 범위는 100%아닙니다. 이러한 필드에 대한 빈 값이 표시 될 수 있습니다.
오류 코드
| 상태 코드 | 오류 범주 | Description | 일반적인 원인 |
|---|---|---|---|
| 200 | Success | 요청이 성공했습니다. | - |
| 400 | 잘못된 요청 | 잘못된 요청 매개 변수입니다. | 필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON |
| 401 | 권한 없음 | 인증이 실패했거나 누락되었습니다. | 잘못된 API 키, x-apikey 헤더 누락 |
| 403 | 사용할 수 없음 | 유효한 자격 증명이지만 권한이 부족합니다. | API 키에 필요한 권한이 없음 |
| 410 | 사라졌다 | HTTPS가 필요합니다. | HTTPS 대신 HTTP를 통해 요청 |
| 415 | 지원되지 않는 미디어 형식 | 콘텐츠 형식은 지원되지 않습니다. | 콘텐츠 형식 헤더가 없거나 잘못되었습니다. |
| 429 | 요청이 너무 많음 | 속도 제한을 초과했습니다. | 시간 창에 요청이 너무 많습니다. |
| 500 | 내부 서버 오류 | 예기치 않은 서버 오류가 발생했습니다. | 임시 서버 문제 |
| 503 | 서비스를 사용할 수 없음 | 서비스를 일시적으로 사용할 수 없습니다. | 유지 관리 또는 임시 중단 |
| 504 | 게이트웨이 시간 제한 | 요청 시간이 초과되었습니다. | 업스트림 서비스 시간 제한 |
자세한 오류 처리 지침은 오류 처리를 참조하세요.