끝점:POST https://api.microsoft.ai/v3/browse
샘플 요청:
curl -X POST "https://api.microsoft.ai/v3/browse" \
-H "host: api.microsoft.ai" \
-H "x-apikey: <Your key>" \
-H "content-type: application/json" \
-d '{
"url": "https://news.microsoft.com/source/",
"maxLength": 3000,
"language": "en",
"region": "US",
"contentFormat": "html"
}'
Parameters
| 매개 변수 | Required | Type | Default | Description |
|---|---|---|---|---|
| url | Yes | string | - | 찾아볼 웹 페이지의 URL입니다. |
| 최대 길이 | No | integer | 10000 | 응답의 콘텐츠 필드에 있는 최대 문자 수입니다. 최대값은 500000자입니다. |
| liveCrawl | No | string | "none" | 라이브 크롤링 동작을 제어합니다. 값: "none"(인덱싱된 콘텐츠만 반환), "대체"(URL이 인덱스에 없는 경우 크롤링), "force"(인덱싱된 콘텐츠가 있는 경우에도 새 크롤링 요청). "none" 값의 경우 인덱스에서 URL을 찾을 수 없는 경우 API는 404 오류 코드(URL을 찾을 수 없음)를 반환합니다. |
| includeWebLinks | No | 부울 | 거짓 | 페이지에서 아웃바운드 하이퍼링크를 포함합니다. |
| renderDynamicPages | No | 부울 | 거짓 | 동적 콘텐츠 스크린샷에 JavaScript 렌더링을 사용하도록 설정합니다. liveCrawl이 "fallback"으로 설정된 경우에만 작동합니다. |
| includeImageLinks | No | 부울 | 거짓 | 페이지의 이미지 URL을 포함합니다. |
| language | No | string | "en" | 언어 코드(2자 ISO 639-1)입니다. 전체 목록은 지원되는 언어 를 참조하세요. |
| region | No | string | "US" | 지역 코드(2자 국가/지역 코드)입니다. 전체 목록은 지원되는 지역을 참조하세요. |
| 콘텐츠 형식 | No | string | "html" | 반환할 웹 페이지 콘텐츠의 형식입니다. "text", "html" 또는 "markdown"일 수 있습니다. |
요청 헤더
| 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 |
|---|---|---|
| url | string | 웹 페이지의 URL입니다. |
| title | string | 웹 페이지의 제목. |
| 콘텐츠 | string | 웹 페이지의 추출된 콘텐츠(즉, 접지)입니다. |
| 마지막 업데이트됨 | string | 웹 페이지의 마지막 업데이트 날짜는 ISO8601 형식을 따릅니다. |
| crawledAt | string | 웹 페이지의 마지막 크롤링 날짜는 ISO8601 형식을 따릅니다. |
| liveCrawlSucceeded | 부울(선택 사항) | 성공한 요청 liveCrawl: "force" 이 부실 페이지를 반환하는 경우에만 존재 false 합니다. 부실 페이지가 아닌 페이지에 대해서는 생략되었습니다. 로 내보내 true지 않습니다. 생략/"none""fallback"null 모드, 재시도(202) 응답에 대해 생략됩니다. |
| traceId | string | 디버깅을 위한 추적 ID입니다. |
| retryAfter | string | 다시 시도하기 전에 대기하는 시간( 접미사가 있는 기간(초)으로 "s" 형식이 지정됩니다(예: "60s" 60초 대기를 의미). 주문형 크롤링이 진행 중인 경우에만 존재합니다. |
| isAdult | 부울 | 웹 페이지에 성인 콘텐츠가 포함되어 있는지를 나타냅니다. |
Note
title, content, isAdultlastUpdatedAt및 crawledAt 필드는 성공(200) 응답에만 존재합니다. 재시도(202) 응답에서 생략됩니다.
예를 들어 부실 콘텐츠가 "liveCrawl": "force" 반환되는 경우에만 포함된 성공적인 요청이 포함 "liveCrawlSucceeded": false 됩니다. 부실하지 않은 페이지는 반환하지 않고 이 필드를 생략합니다 true. 이 필드는 찾아보기 MCP 도구의 구조화된 응답에서 동일한 의미를 가합니다.
오류 코드
| 상태 코드 | 오류 범주 | Description | 일반적인 원인 |
|---|---|---|---|
| 200 | Success | 요청이 성공했습니다. | - |
| 202 | 수락됨 | 처리 요청이 수락되었습니다(라이브 크롤링). | 진행 중인 주문형 크롤링 |
| 400 | 잘못된 요청 | 잘못된 요청 매개 변수입니다. | 필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON |
| 401 | 권한 없음 | 인증이 실패했거나 누락되었습니다. | 잘못된 API 키, x-apikey 헤더 누락 |
| 403 | 사용할 수 없음 | 유효한 자격 증명이지만 요청을 처리할 수 없습니다. | API 키에 필요한 권한이 없음, 정책에 의해 차단된 URL, 필터링된 콘텐츠 |
| 404 | 찾을 수 없음 | 문서를 찾을 수 없습니다. | 잘못되었거나 액세스할 수 없는 URL |
| 410 | 사라졌다 | HTTPS가 필요합니다. | HTTPS 대신 HTTP를 통해 요청 |
| 415 | 지원되지 않는 미디어 형식 | 콘텐츠 형식은 지원되지 않습니다. | 콘텐츠 형식 헤더가 없거나 잘못되었습니다. |
| 429 | 요청이 너무 많음 | 속도 제한을 초과했습니다. | 시간 창에 요청이 너무 많습니다. |
| 430 | 주문형 크롤링이 너무 많습니다. | 주문형 크롤링이 너무 많습니다. | 과도한 라이브 크롤링 요청 |
| 500 | 내부 서버 오류 | 예기치 않은 서버 오류가 발생했습니다. | 임시 서버 문제 |
| 503 | 서비스를 사용할 수 없음 | 서비스를 일시적으로 사용할 수 없습니다. | 유지 관리 또는 임시 중단 |
| 504 | 게이트웨이 시간 제한 | 요청 시간이 초과되었습니다. | 업스트림 서비스 시간 제한 |
자세한 오류 처리 지침은 오류 처리를 참조하세요.