News Search REST API 참조

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

샘플 요청:

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

Parameters

매개 변수	Required	Type	Default	Description
query	Yes	string	-	뉴스 결과에 대한 검색 쿼리입니다. 최대 길이는 1000자입니다.
maxResults	No	integer	10	반환할 최대 결과 수입니다. 기본값은 10입니다. 최대값은 20입니다.
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"(전체 문서 액세스 권한이 있는 "텍스트")	passage 는 쿼리와 가장 관련된 각 결과의 부분을 반환합니다(접지에 권장됨). text html 전체 문서를 반환하고 markdown 전체 문서 액세스 권한이 있는 애플리케이션에만 적용합니다. 구절 및 콘텐츠 형식을 참조하세요. 모든 요청에 대해 설정합니다.
최대 길이	No	integer	3000(전체 문서 액세스 권한이 있는 10000)	결과당 최대 문자 수 content (1~500000)입니다. 전체 문서 액세스 권한이 content 없으면 최대 3,000자입니다. 기본값 및 제한을 참조하세요. 모든 요청에 대해 설정합니다.

콘텐츠 형식

쿼리와 가장 관련된 각 결과의 부분을 최대 문자(3,000개는 좋은 시작점)까지 가져올 수 있도록 설정합니다contentFormatpassage = .maxLength 접지에 권장되는 형식입니다. FAQ에서 passage무엇이고 왜 사용합니까? 전체 문서 액세스 권한이 있는 애플리케이션은 전체 문서를 다른 응용 프로그램의 경우 HTTP 403으로 texthtmlmarkdown요청할 수도 있습니다. 구절 및 콘텐츠 형식을 참조하세요.

요청 헤더

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
newsResults	newsResult의 배열	뉴스 기사 결과 목록입니다.
instrumentationClickBase	string	ping 요청을 클릭하기 위한 기본 URL입니다. 결과 항목의 instrumentationSuffix 값을 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다. 참고: URL 리디렉션을 사용하여 사용자 클릭을 기록할 수도 있습니다. 리디렉션을 사용하도록 설정하면 사용자 클릭을 기록하는 작업이 필요하지 않으며 instrumentationClickBase 응답에 포함되지 않습니다. 설치 지침은 계측 가이드 를 참조하세요.
instrumentationCitationBase	string	LLM 로그 ping 요청에 대한 기본 URL입니다. 데이터 페이로드를 추가하여 전체 ping URL을 형성합니다. EnableInstrumentationPing 프로필 플래그가 있는 애플리케이션에만 존재합니다.
traceId	string	디버깅을 위한 추적 ID입니다.

newsResult

Field	Type	Description
title	string	뉴스의 제목입니다.
url	string	뉴스 기사의 원본 URL입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자의 경우 이 필드에는 .와 동일한 리디렉션 URL clickUrl이 대신 포함됩니다.
domain	string	결과의 대상 호스트입니다. URL 리디렉션을 사용하도록 설정된 중국 사용자에 대해서만 반환됩니다.
콘텐츠	string	뉴스 결과의 자세한 웹 페이지 콘텐츠(즉, 접지)입니다.
섬네일	썸네일 개체	뉴스 기사의 썸네일입니다.
마지막 업데이트됨	string	마지막으로 업데이트된 뉴스 날짜(UTC ISO8601 형식)입니다.
crawledAt	string	뉴스의 마지막 크롤링 날짜는 ISO8601 형식을 따릅니다.
language	string	뉴스 기사의 언어는 ISO 639-1 언어 코드를 사용합니다.
source	string	Publisher 이름(예: "USA TODAY | MSN", "CNN" 등
isAdult	부울	콘텐츠가 성인인지를 나타냅니다.
clickUrl	string	Bing을 통해 클릭을 프록시하는 URL을 리디렉션합니다. 클릭 리디렉션을 사용하는 경우에만 존재합니다.
instrumentationSuffix	string	이 결과 항목의 계측 ping URL 베이스에 추가할 접미사입니다. 계측 ping URL과 리디렉션 모두에 대한 K 값으로 clickUrl 사용됩니다. 계측 ping을 사용할 때 표시됩니다.

Note

lastUpdatedAt 필드는 선택 사항입니다. 즉, 이 필드에 빈 값이 표시 될 수 있습니다.

섬네일

Field	Type	Description
url	string	썸네일의 URL입니다.
width	integer	축소판 그림의 너비(픽셀)입니다.
height	integer	썸네일의 높이(픽셀)입니다.

Note

thumbnail 는 선택적 응답 개체이기도 합니다. 특정 뉴스 결과에는 사용할 수 없습니다.

오류 코드

상태 코드	오류 범주	Description	일반적인 원인
200	Success	요청이 성공했습니다.	-
400	잘못된 요청	잘못된 요청 매개 변수입니다.	필수 필드 누락, 잘못된 매개 변수 값, 형식이 잘못된 JSON
401	권한 없음	인증이 실패했거나 누락되었습니다.	잘못된 API 키, x-apikey 헤더 누락
403	사용할 수 없음	유효한 자격 증명이지만 권한이 부족합니다.	API 키에 필요한 권한이 없음
410	사라졌다	HTTPS가 필요합니다.	HTTPS 대신 HTTP를 통해 요청
415	지원되지 않는 미디어 형식	콘텐츠 형식은 지원되지 않습니다.	콘텐츠 형식 헤더가 없거나 잘못되었습니다.
429	요청이 너무 많음	속도 제한을 초과했습니다.	시간 창에 요청이 너무 많습니다.
500	내부 서버 오류	예기치 않은 서버 오류가 발생했습니다.	임시 서버 문제
503	서비스를 사용할 수 없음	서비스를 일시적으로 사용할 수 없습니다.	유지 관리 또는 임시 중단
504	게이트웨이 시간 제한	요청 시간이 초과되었습니다.	업스트림 서비스 시간 제한

자세한 오류 처리 지침은 오류 처리를 참조하세요.

---

참고 항목:웹 검색 | 비디오 검색 | 이미지 검색 | | MCP