Microsoft Web IQ API에 인증하여 액세스하는 방법은 두 가지입니다. 가장 빠르게 시작하려면 API 키를 사용하고, 프로덕션 워크로드에는 Microsoft Entra ID를 사용합니다.
API 키
Microsoft Web IQ 포털에서 API 키를 만들어 Microsoft Web IQ API 인증에 사용합니다. 모든 요청에서 x-apikey 헤더로 전달하세요.
x-apikey: <YOUR_API_KEY>
Warning
API 키는 계정에 대한 모든 액세스 권한을 부여합니다. 클라이언트 쪽 코드 또는 소스 제어가 아닌 시크릿 관리자에 저장합니다.
Microsoft Entra ID (마이크로소프트 엔트라 ID)
Microsoft Web IQ API에 인증하려면 Microsoft Entra ID OAuth 2.0 클라이언트 자격 증명(앱 전용 토큰)을 사용합니다.
Note
Microsoft Entra ID는 ID 관리 플랫폼입니다. 앱 등록에는 테넌트에서 애플리케이션을 식별하고 Web IQ 계정에 바인딩하는 값인 애플리케이션 (클라이언트) ID가 있습니다. 런타임에 앱은 각 API 요청과 함께 보내기 위해 자격 증명을 Microsoft Entra 액세스 토큰으로 교환합니다.
사전 요구 사항
테넌트 설정: 앱을 등록하려면 Azure 테넌트가 필요합니다. Azure 구독은 필요하지 않지만 조직에 이미 하나 이상의 Azure 구독 또는 Microsoft 365 조직이 있는 경우 이미 Azure 테넌트가 있습니다. 그렇지 않으면 새 테넌트를 프로비전합니다.
앱 등록 만들기: 앱 등록은 애플리케이션과 Microsoft ID 플랫폼 간에 트러스트 관계를 설정하여 앱이 안전하게 인증하고 리소스에 액세스할 수 있도록 합니다.
앱을 등록하면 클라이언트 ID, 개체 ID 및 디렉터리 ID가 만들어집니다. 앱 등록을 위한 자격 증명을 만들려면 Microsoft ID 플랫폼을 사용하여 애플리케이션 등록을 참조하세요.
Entra ID 설정 단계
앱 등록 - 기존 Microsoft Entra ID 앱 등록을 사용하거나 만듭니다. 애플리케이션(클라이언트) ID를 기록합니다. Azure 포털에서 Microsoft Entra ID>앱 등록>해당 앱>개요에서 찾을 수 있습니다.
앱 등록 바인딩 - 프로필 관리로 이동하여 애플리케이션(클라이언트) ID 탭을 선택한 다음 애플리케이션(클라이언트) ID 바인딩을 선택합니다. 애플리케이션(클라이언트) ID를 입력합니다. 프로필 업데이트는 동기화하는 데 최대 1분이 걸릴 수 있습니다.
Note
애플리케이션(클라이언트) ID 탭을 사용할 수 없는 경우 Microsoft Entra ID 인증이 평가판에 사용하도록 설정되지 않을 수 있습니다. 전용 액세스를 요청하려면 Microsoft 담당자에게 문의하세요.
토큰 획득 - 선호하는 Microsoft 인증 라이브러리(MSAL)를 사용하여 클라이언트 자격 증명 부여를 사용하세요:
- 권한:
https://login.microsoftonline.com/{your-tenant-id} - 범위:
https://api.microsoft.ai/.default
- 권한:
그런 다음, 모든 Web IQ 요청에 액세스 토큰을 전달합니다.
Authorization: Bearer <access-token>
둘 이상의 AppID를 호출
하나의 애플리케이션(클라이언트) ID를 둘 이상의 Web IQ AppID에 바인딩할 수 있습니다(예: 웹 IQ 리소스당 하나 또는 워크로드당 하나의 AppID). 이 경우 모든 요청마다 APPID 쿼리 매개 변수를 추가하여 호출에서 사용하는 AppID를 선택합니다. 속도 제한은 해당 AppID에 대해 집계됩니다.
POST https://api.microsoft.ai/v3/search/web?APPID=<your-web-iq-appid>
Authorization: Bearer <access-token>
Content-Type: application/json
APPID 는 애플리케이션(클라이언트) ID가 아닌 Web IQ AppID를 사용합니다. 귀하의 Microsoft 담당자가 Web IQ AppID를 제공합니다.
| 애플리케이션(클라이언트) ID가 바인딩되어 있습니다. |
APPID 요청에 |
Result |
|---|---|---|
| One AppID | 누락되었거나 해당 AppID인 경우 | 요청이 성공했습니다 |
| AppID 하나 | 다른 AppID | HTTP 403 AuthUnauthorizedAppId |
| 여러 개의 AppID | 누락되거나 비어 있음 | HTTP 400 AuthAppIdSelectionRequired |
| 여러 AppID | 바인딩된 AppID 중 하나 | 요청이 성공했습니다 |
| 여러 AppIDs | 기타 AppID | HTTP 403 AuthUnauthorizedAppId |
| AppID 없음 | 모두 | HTTP 401 AuthUnauthorizedEntryId |
Warning
API 키는 APPID 허용하지 않습니다. 각 API 키는 하나의 AppID에 속합니다.
APPID 매개 변수가 포함된 키 인증 요청은, 해당 매개 변수가 비어 있어도 HTTP 401 AuthUnauthorizedEntryId을 반환합니다.
요청 헤더
| Header | Value | Description |
|---|---|---|
x-apikey 또는 Authorization |
<your-api-key> 또는 Bearer <access-token> |
인증을 위한 API 키 또는 Microsoft Entra ID 액세스 토큰 |
Content-Type |
application/json |
요청 본문 형식 |
다음 단계
- 빠른 시작에서 첫 번째 호출을 수행하세요.
- REST API 참조를 탐색합니다.
지원 및 피드백
웹 IQ 지원에 기술 문제 또는 피드백을 보냅니다.