빠른 시작: 첫 번째 Web IQ API 호출

몇 분 안에 첫 번째 Microsoft Web IQ REST API 호출을 만듭니다. 웹을 검색하고, 응답을 검사한 다음, 알려진 URL에서 콘텐츠를 추출합니다.

API 키는 Web IQ를 평가하는 가장 빠른 방법입니다. 프로덕션 워크로드의 경우 Microsoft Entra ID 사용합니다.

사전 요구 사항

프로필 관리의 Web IQ API 키입니다.

Tip

Web IQ Playground를 사용하여 브라우저에서 요청을 보내고 cURL, Python, JavaScript, C#, Java, Go 및 Ruby로 코드를 생성합니다.

1. API 키를 저장하세요

요청 예제에서 키를 반복하지 않고 소스 코드에 넣지 않도록 키를 환경 변수에 저장합니다.

macOS 또는 Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

$env:WEBIQ_API_KEY="your-api-key"

Warning

소스 제어에 키를 커밋하거나 브라우저 또는 클라이언트 쪽 코드에 노출하지 마세요. 프로덕션 자격 증명을 Secret Manager에 저장합니다.

2. 웹 검색

질문이나 쿼리가 있고 Web IQ가 관련 페이지를 찾아 순위를 매기도록 하려는 경우 Web Search를 사용합니다.

모든 요청에 대해 maxResults = 10, contentFormat = passage, maxLength = 3000를 최적화된 운영 지점으로 설정하는 것이 좋습니다. 여기에서 사용 사례에 따라 이러한 설정을 미세 조정할 수 있습니다.

끝점:POST https://api.microsoft.ai/v3/search/web

cURL

curl --request POST "https://api.microsoft.ai/v3/search/web" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "latest developments in retrieval augmented generation",
    "maxResults": 10,
    "contentFormat": "passage",
    "maxLength": 3000
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/web",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "latest developments in retrieval augmented generation",
        "maxResults": 10,
        "contentFormat": "passage",
        "maxLength": 3000,
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

자바 스크립트

이 예제를 search.mjs(으)로 저장하고 node search.mjs를 사용하여 실행합니다.

const response = await fetch("https://api.microsoft.ai/v3/search/web", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "latest developments in retrieval augmented generation",
    maxResults: 10,
    contentFormat: "passage",
    maxLength: 3000,
  }),
});

if (!response.ok) {
  throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

3. 응답 이해하기

성공적인 Web Search는 webResults 배열을 반환합니다. 이 약어 예제에서는 가장 자주 사용할 필드를 보여 줍니다.

{
  "webResults": [
    {
      "title": "Example result",
      "url": "https://example.com/article",
      "content": "The query-relevant passage extracted from the page...",
      "crawledAt": "2026-07-18T12:00:00Z"
    }
  ],
  "traceId": "00000000000000000000000000000000"
}

title 및 url이 원본을 식별합니다.
content에는 요청에서 contentFormat: "passage"를 사용했기 때문에 쿼리 관련 문단이 포함됩니다.
traceId 는 Web IQ 지원에서 요청을 조사하는 데 도움이 됩니다.

REST 응답 및 MCP 도구 결과에서 중첩된 결과 개체의 필드를 포함하여 "", 빈 문자열([]), 또는 빈 목록/배열(null) 값이 있는 모델 필드는 생략됩니다. 없는 문자열 필드를 사용할 수 없는 것으로 간주하고 없는 목록 필드를 항목이 없는 것으로 처리합니다. 공백 전용 문자열, false, 0, 빈 사전, 개별 배열/사전 항목 및 포함된 원시 JSON이 유지됩니다. 루트 배열 및 MCP content 와 같은 프로토콜 엔벌로프 컬렉션은 변경되지 않습니다.

모든 매개 변수 및 응답 필드에 대한 Web Search API 참조 를 참조하세요.

4. 웹 검색 또는 찾아보기를 선택합니다

시작하기	사용	얻을 수 있는 것
질문 또는 검색 쿼리	웹 검색	쿼리 관련 콘텐츠가 있는 순위가 지정된 페이지
특정 URL	찾아보기	해당 페이지에서 추출된 콘텐츠

일반적인 그라운딩 워크플로는 두 엔드포인트를 모두 사용합니다. 관련 원본을 검색하고, 결과 URL을 선택한 다음, 더 완전한 페이지 콘텐츠가 필요할 때 해당 URL을 탐색합니다.

5. URL에서 콘텐츠 추출

읽을 페이지를 이미 알고 있는 경우 찾아보기를 사용합니다. liveCrawl: "fallback" 인덱스에 아직 없는 경우 웹 IQ에 페이지를 크롤링하도록 요청합니다.

끝점:POST https://api.microsoft.ai/v3/browse

cURL

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://news.microsoft.com/source/",
    "contentFormat": "markdown",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/browse",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "url": "https://news.microsoft.com/source/",
        "contentFormat": "markdown",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

자바 스크립트

이 예제를 browse.mjs(으)로 저장하고 node browse.mjs를 사용하여 실행합니다.

const response = await fetch("https://api.microsoft.ai/v3/browse", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://news.microsoft.com/source/",
    contentFormat: "markdown",
    maxLength: 3000,
    liveCrawl: "fallback",
  }),
});

if (!response.ok) {
  throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

성공적인 200 응답에는 페이지 url, title, 추출된 content, 및 응답 traceId가 포함됩니다. 라이브 크롤링은 202와 함께 retryAfter를 반환할 수 있습니다. 해당 기간을 기다린 다음 동일한 요청을 다시 보냅니다. 전체 응답 사양에 대한 찾아보기 API 참조를 참조하세요.

Troubleshooting

Status	확인할 사항
`401 Unauthorized`	`WEBIQ_API_KEY`이 설정되어 있고 요청이 `x-apikey` 헤더에 이를 전송하는지 확인하세요.
`415 Unsupported Media Type`	전송합니다 `content-type: application/json`.
`429 Too Many Requests`	다시 시도하기 전에 기다렸다가 요청 빈도를 줄이세요.
찾아보기 `404 Not Found`	URL이 공개되어 있고 유효한지 확인하세요. 인덱싱된 콘텐츠를 사용할 수 없을 수 있는 경우 `liveCrawl: "fallback"`를 사용합니다.
찾아보기 `202 Accepted`	반환된 `retryAfter` 시간 동안 기다린 다음 동일한 요청을 다시 시도합니다.

다른 실패의 경우 traceId를 저장하고 오류 처리를 참조하거나 Web IQ 지원에 문의하세요.

다음 단계

웹 검색 및 찾아보기 API 참조를 탐색합니다.
Python 및 TypeScript SDK를 사용합니다.
Claude Code, Cursor 또는 VS Code에 MCP 서버를 설치합니다.
Microsoft Entra ID를 사용하여 프로덕션 인증을 설정합니다.

피드백

이 페이지가 도움이 되었나요?

2026-10-16 에 마지막으로 업데이트됨

빠른 시작: 첫 번째 Web IQ API 호출

사전 요구 사항

1. API 키를 저장하세요

macOS 또는 Linux

Windows PowerShell

2. 웹 검색

cURL

Python

자바 스크립트

3. 응답 이해하기

4. 웹 검색 또는 찾아보기를 선택합니다

5. URL에서 콘텐츠 추출

cURL

Python

자바 스크립트

Troubleshooting

다음 단계

피드백

추가 리소스