Note
foundry IQ(Azure AI 검색)는 관리 검색을 위해 고급 기술 자료 및 기술 자료 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
사용자 지정 웹 API 기술을 사용하여 사용자 지정 작업을 제공하는 Web API 엔드포인트를 호출하여 AI 보강을 확장합니다. 기본 제공 기술과 마찬가지로 사용자 지정 Web API 기술에는 입력 및 출력이 있습니다. 입력에 따라 Web API는 인덱서가 실행될 때 JSON 페이로드를 수신하고 성공 상태 코드와 함께 JSON 페이로드를 응답으로 반환합니다. 응답에는 사용자 지정 기술에서 지정한 출력이 포함되어야 합니다. 다른 응답은 오류로 간주되며 강화는 수행되지 않습니다. JSON 페이로드의 구조는 이 문서의 뒷부분에 설명되어 있습니다.
사용자 지정 Web API 기술은 Azure OpenAI On Your Data 기능의 구현에도 사용됩니다. Azure OpenAI가 역할 기반 액세스에 대해 구성되고 벡터 인덱스를 만들 때 오류가 발생하는 403 Forbidden 경우 Foundry IQ(Azure AI 검색)에 시스템 할당 ID가 있고 Azure OpenAI에서 신뢰할 수 있는 서비스로 실행되는지 확인합니다.
Note
인덱서는 웹 API에서 반환된 특정 표준 HTTP 상태 코드에 대해 두 번 다시 시도합니다. 이러한 HTTP 상태 코드는 다음과 같습니다.
502 Bad Gateway503 Service Unavailable429 Too Many Requests
@odata.type
Microsoft.Skills.Custom.WebApiSkill
기술 매개 변수
매개 변수는 대/소문자를 구분합니다.
| 매개 변수 이름 | Description |
|---|---|
uri |
JSON 페이로드가 전송되는 웹 API의 URI입니다.
https URI 체계만 허용됩니다. GET 및 LIST 응답은 포함 sig 및 code. 저장된 URI를 변경하지 않고 기술을 업데이트하려면 전체를 uri<unchanged>.로 설정합니다. 반환된 자리 표시자 및 일치 규칙은 URI 편집 및 자격 증명 유지 업데이트를 참조하세요. |
authResourceId |
(선택 사항) 설정할 때 이 기술이 코드를 호스팅하는 함수 또는 앱에 대한 연결에서 시스템 관리 ID를 사용해야 임을 나타내는 문자열입니다. 이 속성은 애플리케이션(클라이언트) ID 또는 앱의 등록을 Microsoft Entra ID 형식으로 사용합니다. api://<appId><appId>/.defaultapi://<appId>/.default 이 값은 인덱서에서 검색한 인증 토큰의 범위를 지정하는 데 사용되며 사용자 지정 웹 API 기술 요청과 함께 함수 또는 앱으로 전송됩니다. 이 속성을 설정하려면 Foundry IQ 서비스가 관리 ID에 대해 구성되고 Azure 함수 앱이 Microsoft Entra 로그인하도록 구성되어야 합니다. 이 매개 변수를 사용하려면 API를 이상과 함께 api-version=2023-10-01-preview 호출합니다. 올바른 값을 선택하는 방법에 대한 지침은 값 이해를 authResourceId 참조하세요. |
authIdentity |
(선택 사항) 코드를 호스트하는 함수 또는 앱에 연결하기 위해 Foundry IQ 서비스에서 사용하는 사용자 관리 ID입니다.
시스템 관리 ID 또는 사용자 관리 ID를 지정할 수 있습니다. 시스템 관리 ID를 사용하려면 비워 둡니다 authIdentity . |
httpMethod |
페이로드를 보내는 데 사용하는 메서드입니다. 허용되는 메서드는 PUT 또는 POST입니다. |
httpHeaders |
키-값 쌍 컬렉션입니다. 여기서 키는 헤더 이름을 나타내고, 값은 페이로드와 함께 Web API로 보낼 헤더 값을 나타냅니다. 헤더 Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via는 이 컬렉션에서 금지됩니다. 전달자 토큰 및 API 키와 같은 자격 증명의 노출을 방지하기 위해 모든 헤더 값에 대한 GET 및 LIST 응답이 반환 <redacted> 됩니다. 동일한 기존 기술 및 엔드포인트에 대해 저장된 헤더 값을 유지하려면 반환 <redacted> 된 값을 다시 제출하거나 사용합니다 <unchanged>. 일치하는 규칙은 URI 편집 및 자격 증명 유지 업데이트를 참조하세요. |
timeout |
(선택 사항) 지정할 경우 API 호출을 수행하는 http 클라이언트에 대한 시간 제한을 나타냅니다. 형식은 XSD "dayTimeDuration" 값( ISO 8601 기간 값의 제한된 하위 집합)이어야 합니다. 예를 들어, 60초인 경우 PT60S입니다. 설정하지 않으면 기본값 30초가 선택됩니다. 시간 제한은 최대 230초, 최소 1초로 설정할 수 있습니다. |
batchSize |
(선택 사항) API 호출당 전송되는 "데이터 레코드"(아래 JSON 페이로드 구조 참조) 수를 나타냅니다. 설정하지 않으면 기본값인 1,000이 선택됩니다. 이 매개 변수를 사용하여 인덱싱 처리량과 API의 로드 간에 적절한 절충을 달성할 수 있습니다. |
degreeOfParallelism |
(선택 사항) 지정된 경우 인덱서가 제공된 엔드포인트와 병렬로 수행하는 호출 수를 나타냅니다. 엔드포인트가 압력을 받고 실패하는 경우 이 값을 줄이거나 엔드포인트가 로드를 처리할 수 있는 경우 값을 높일 수 있습니다. 설정하지 않으면 기본값으로 5초가 사용됩니다.
degreeOfParallelism은 최대 10자, 최소 1자로 설정할 수 있습니다. |
값 이해 authResourceId
사용자 지정 Web API 기술이 관리 ID 인증을 사용하는 경우 Foundry IQ는 Microsoft Entra 액세스 토큰을 가져와서 사용자 지정 기술 엔드포인트로 보냅니다. 이 속성은 authResourceId 토큰이 요청되는 대상 그룹 또는 애플리케이션 ID URI라고도 하는 리소스 식별자를 지정합니다. 값은 토큰 유효성 검사 중에 대상 애플리케이션이 기대하는 것과 일치해야 합니다. 그렇지 않으면 응답과 함께 인증이 실패합니다 401 Unauthorized .
이 값은 authResourceId 사용자 지정 기술을 호스팅하는 애플리케이션을 식별합니다. Foundry IQ 서비스 또는 인덱서의 URL이 아닙니다.
다음 표에서는 일반적인 형식을 보여 줍니다.
| 대상 애플리케이션 |
authResourceId 값 |
|---|---|
| 보호된 웹 애플리케이션 Microsoft Entra | api://<application-client-id> |
| 사용자 지정 애플리케이션 ID URI로 구성된 애플리케이션 | 사용자 지정 애플리케이션 ID URI(예: ) api://contoso-customskill |
| Microsoft Entra ID 의해 보호되는 Azure 함수 | 함수 앱의 앱 등록에 대해 구성된 애플리케이션 ID URI(예: api://contoso-funcapp |
이 속성은 범위 접미사가 있는 형식과 없는 형식을 .default 허용합니다. 애플리케이션 ID URI를 직접 일치시킬 때 사용합니다 api://<appId> . 접미사와 같은 .default접미사를 포함하는 api://<appId>/.default 경우 액세스 토큰의 aud 클레임에는 접미사가 없는 기본 애플리케이션 ID URI가 포함됩니다.
Azure 함수에 대한 Microsoft Entra 인증을 구성하고 설정하는 authResourceId단계는 Foundry IQ 서비스 관리 ID를 사용하여 Azure 함수 앱에 연결하는 단계를 참조하세요.
예: Microsoft Entra ID 의해 보호되는 Azure 함수
이 예제에서 Foundry IQ는 지정된 authResourceId 대상 그룹에 대한 액세스 토큰을 획득하고 사용자 지정 기술 엔드포인트를 호출할 때 토큰을 포함합니다.
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"uri": "https://contoso-function.azurewebsites.net/api/enrich",
"authResourceId": "api://contoso-customskill"
}
기술 입력
이 기술에는 미리 정의된 입력이 없습니다. 입력은 사용자 지정 기술에 전달하려는 기존 필드 또는 보강 트리의 노드입니다.
기술 성과
이 기술에는 미리 정의된 출력이 없습니다. 기술의 출력을 검색 인덱스의 필드로 보내야 하는 경우 인덱서에서 출력 필드 매핑을 정의해야 합니다.
샘플 정의
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "A custom skill that can identify positions of different phrases in the source text",
"uri": "https://contoso.count-things.com",
"batchSize": 4,
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "language",
"source": "/document/languageCode"
},
{
"name": "phraseList",
"source": "/document/keyphrases"
}
],
"outputs": [
{
"name": "hitPositions"
}
]
}
URI 편집 및 자격 증명 유지 업데이트
이 URI 쿼리 동작은 모든 API 버전에 적용됩니다.
LIST를 사용하여 GET 또는 목록 기술 세트를 사용하여 기술 세트를 검색하는 경우 Foundry IQ는 중요한 사용자 지정 웹 API 기술() URI 쿼리 값(WebApiSkill포함 및 codeHTTP 헤더 값)sig을 수정합니다. 이러한 수정된 값은 SAS(공유 액세스 서명) 서명, 함수 키 및 헤더 자격 증명을 보호합니다.
새 기술 세트 또는 복사된 기술의 경우 대상 엔드포인트의 필수 쿼리 및 헤더 비밀을 제공하거나 지원되는 관리 ID 인증 및 권한 부여를 구성합니다. 반환 <redacted> 된 <unchanged> 자리 표시자와 자리 표시자는 자격 증명이 아닙니다.
저장된 비밀을 유지하려면 동일한 엔드포인트에서 동일한 기존 기술 세트와 일치하는 사용자 지정 Web API 기술을 업데이트합니다. 보존된 헤더는 기존 헤더 이름과 일치해야 하며, 서비스는 명확한 원본 기술을 식별해야 합니다. 반환되거나 <redacted><unchanged> 자리 표시자를 관리 PUT 요청에 대한 전체 기술 세트 정의에 제출합니다. 이 PUT은 기술 세트 정의를 업데이트합니다. 기술에서 제어하는 엔드포인트 호출이 httpMethod아닙니다. 저장된 URI를 유지하도록 <unchanged> 전체를 uri 설정할 수도 있습니다.
엔드포인트를 변경하려면 명시적 대상 자격 증명이 필요합니다. 저장된 비밀은 전송되지 않습니다.
서비스에서 자리 표시자에 대한 명확한 기존 원본을 식별할 수 없는 경우 PUT은 실패 400 Bad Request 하고 실제 비밀 값을 요청합니다. 해결되지 않거나 지속형 자리 표시자는 사용할 수 있는 자격 증명이 아닙니다. 비밀 복원은 원자성입니다. 실패한 복원은 URI 또는 헤더 변경 내용을 부분적으로 적용하지 않습니다.
언제든지 대체 URI 또는 헤더 비밀을 제공할 수 있습니다. 명시적 값이 자리 표시자보다 우선합니다.
URI 쿼리 업데이트는 다음 규칙을 따릅니다.
- Azure 함수
code매개 변수의 경우 동일한 엔드포인트에 대해 저장된 함수 키를 유지하면서 다른 비밀이 아닌 쿼리 매개 변수를 업데이트할 수 있습니다. - SAS
sig매개 변수의 경우 서명은 주변 비비밀 쿼리 구성에 바인딩됩니다. 범위, 사용 권한, 만료, 리소스, 버전, 순서 지정, 대/소문자 또는 인코딩이 변경되는 경우 새 서명을 제공합니다. 의미상 동등한 순서가 다시 정렬되거나 다시 인코딩된 쿼리 텍스트에도 새 서명이 필요합니다.
비밀 쿼리 매개 변수 이름은 대/소문자를 구분하지 않으며 백분율로 인코딩된 경우 인식됩니다. 서비스는 정규화하지 않고 URI 표현을 유지합니다. 반복되는 비밀 매개 변수는 발생과 일치합니다. 해당 발생 패턴이 저장된 URI와 더 이상 일치하지 않는 경우 실제 값을 제공합니다.
기존 GET-then-PUT 워크플로를 사용 <redacted> 하거나 <unchanged> 계속 지원합니다.
쿼리 시간 벡터화는 사용자 지정 Web API 벡터라이저 URI 편집 및 자격 증명 유지 업데이트를 참조하세요.
다음 GET 응답은 함수 키 및 헤더 값을 수정합니다. 이러한 값을 유지하려면 동일한 기술과 엔드포인트를 업데이트합니다.
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"uri": "https://contoso.example.org/api?code=<redacted>",
"httpMethod": "POST",
"name": "myCustomSkill",
"httpHeaders": {
"Authorization": "<redacted>",
"Ocp-Apim-Subscription-Key": "<redacted>"
}
}
전체 URI 및 기존 헤더 값을 유지하려면 동일한 기술의 전체 정의에서 이러한 속성을 사용합니다 <unchanged> . 다음 조각은 독립 실행형 만들기 또는 업데이트 요청이 아닙니다.
{
"uri": "<unchanged>",
"httpHeaders": {
"Authorization": "<unchanged>",
"Ocp-Apim-Subscription-Key": "<unchanged>"
}
}
매개 변수 세부 정보는 기술 매개 변수를 참조하세요.
이러한 규칙은 모든 비밀 베어링 기술이 아닌 사용자 지정 Web API URI 및 헤더 속성에 적용됩니다. 보안 내보내기 및 종속성 레크리에이션 시퀀스는 인덱스 백업, 복원 또는 복제를 참조하세요.
샘플 입력 JSON 구조
이 JSON 구조는 Web API로 보내는 페이로드를 나타냅니다. 항상 다음 제약 조건을 따릅니다.
최상위 엔터티는
values라고 하며 개체 배열입니다. 이러한 개체의 수는 최대 입니다batchSize.values배열의 각 개체에는 다음이 포함됩니다.recordId해당 레코드를 식별하는 데 사용되는 고유한 문자열인 속성입니다.dataJSON 개체인 속성입니다. 속성의data필드는 기술 정의 섹션에 지정된 "이름"에inputs해당합니다. 이러한 필드의 값은 해당 필드(문서의 필드 또는 다른 기술에서 발생할 수 있음)에서 가져옵니다source.
{
"values": [
{
"recordId": "0",
"data":
{
"text": "Este es un contrato en Inglés",
"language": "es",
"phraseList": ["Este", "Inglés"]
}
},
{
"recordId": "1",
"data":
{
"text": "Hello world",
"language": "en",
"phraseList": ["Hi"]
}
},
{
"recordId": "2",
"data":
{
"text": "Hello world, Hi world",
"language": "en",
"phraseList": ["world"]
}
},
{
"recordId": "3",
"data":
{
"text": "Test",
"language": "es",
"phraseList": []
}
}
]
}
샘플 출력 JSON 구조
“출력”은 Web API에서 반환되는 응답에 해당합니다. 이 Web API는 JSON 페이로드(Content-Type 응답 헤더를 보고 확인)만 반환해야 하며 다음 제약 조건을 충족해야 합니다.
개체 배열에 해당하는
values라는 최상위 엔터티가 있어야 합니다.배열의 개체 수는 Web API로 보낸 개체 수와 같아야 합니다.
각 개체에는 다음이 지정되어야 합니다.
recordId속성입니다.data속성: 필드가output의 “names”와 일치하는 강화에 해당하는 개체이며, 해당 값이 보강으로 간주됩니다.errors속성은 인덱서 실행 기록에 추가되어 발생한 오류를 나열하는 배열입니다. 이 속성은 필요하지만 값이null일 수 있습니다.warnings속성은 인덱서 실행 기록에 추가되고 발생한 모든 경고를 나열하는 배열입니다. 이 속성은 필요하지만 값이null일 수 있습니다.
요청 또는 응답에서
values의 개체 순서는 중요하지 않습니다. 그러나recordId는 상관 관계에 사용되므로 웹 API에 대한 원래 요청의 일부가 아닌recordId를 포함하는 응답의 모든 레코드는 삭제됩니다.
{
"values": [
{
"recordId": "3",
"data": {
},
"errors": [
{
"message" : "'phraseList' should not be null or empty"
}
],
"warnings": null
},
{
"recordId": "2",
"data": {
"hitPositions": [6, 16]
},
"errors": null,
"warnings": null
},
{
"recordId": "0",
"data": {
"hitPositions": [0, 23]
},
"errors": null,
"warnings": null
},
{
"recordId": "1",
"data": {
"hitPositions": []
},
"errors": null,
"warnings": [
{
"message": "No occurrences of 'Hi' were found in the input text"
}
]
}
]
}
오류 사례
Web API를 사용할 수 없거나 성공하지 못한 상태 코드를 보내는 것 외에도 다음 사례를 오류로 간주합니다.
Web API가 성공 상태 코드를 반환하지만 응답이 그렇지 않음을 나타내는 경우 응답은 유효하지
application/json않으며 보강이 수행되지 않습니다.응답
values배열에 잘못된 레코드(예: 누락 또는 중복됨)가recordId포함되어 있으면 잘못된 레코드가 보강되지 않습니다. 사용자 지정 기술을 개발할 때 Web API 기술 계약을 준수합니다. 예상 계약을 따르는 Power Skill 리포지토리에 제공된 이 예제를 참조할 수 있습니다.
Web API를 사용할 수 없거나 HTTP 오류를 반환하는 경우 인덱서 실행 기록에는 HTTP 오류에 대한 사용 가능한 세부 정보가 포함된 친숙한 오류가 포함됩니다.
관리 ID 인증에 대한 보안 고려 사항
사용자 지정 Web API 기술로 관리 ID 인증을 사용하는 경우 Foundry IQ는 식별된 authResourceId 애플리케이션에 대한 Microsoft Entra 액세스 토큰을 가져오고 지정된 엔드포인트로 전송된 uri요청에 해당 토큰을 포함합니다. 참조되는 uri 엔드포인트는 일반적으로 Azure 함수, Azure App Service, Azure API Management 엔드포인트 또는 다른 Microsoft Entra 보호된 애플리케이션입니다. 엔드포인트와 다음으로 식별되는 authResourceId애플리케이션 간의 관계를 구성하고 유지 관리해야 합니다.
인증 방법에 관계없이 사용자 지정 기술 입력에는 고객이 제공한 문서의 값이나 해당 문서에서 파생된 값이 포함될 수 있습니다. 모든 사용자 지정 기술 입력을 신뢰할 수 없는 것으로 처리합니다. Foundry IQ는 사용자 지정 구현을 위해 콘텐츠를 해석, 유효성 검사 또는 제한하지 않고 기술 세트에 구성된 입력을 엔드포인트로 전달합니다.
아웃바운드 요청 또는 기타 보안에 민감한 작업에서 사용하기 전에 사용자 지정 기술에서 문서 파생 값의 유효성을 검사하고 제한합니다. 입력 유효성 검사, 대상 허용 목록, URL 및 호스트 이름 유효성 검사, 프로토콜 제한 및 기술에 필요한 대상 및 포트만 허용하는 최소 권한 네트워크 액세스를 사용합니다. 자세한 내용은 네트워킹 및 연결에 대한 아키텍처 전략을 참조하세요.
권장 보안 방법
보안 배포를 유지 관리하려면 다음 방법을 따르세요.
-
uriFoundry IQ에서 요청을 수신하기 위한 신뢰할 수 있는 엔드포인트만 가리키도록 속성을 구성합니다. - 액세스 토큰을 수신하고 유효성을 검사해야 하는 Microsoft Entra 애플리케이션을 식별하도록 구성
authResourceId합니다. - 요청을 수신하는 애플리케이션이 요청을 처리하기 전에 대상 그룹(), 발급자(
aud), 테넌트(isstid) 및 필요한 애플리케이션 역할 또는 권한을 포함한 표준 토큰 클레임의 유효성을 검사해야 합니다. - Foundry IQ 관리 ID에 권한을 부여할 때 최소 권한 원칙을 적용합니다.
- Foundry IQ 관리 ID에 부여된 사용자 지정 Web API 기술 정의, Microsoft Entra 애플리케이션 등록 및 앱 역할 할당 및 권한을 주기적으로 검토합니다. 설정된 변경 관리 및 보안 검토 프로세스를 통해 구성 변경 내용을 검토합니다.
- Azure Functions, App Services, API 및 API 게이트웨이에 대한 엔드포인트 구성을 주기적으로 검토합니다.
- 애플리케이션 로그인 로그, 인증 이벤트 및 API 액세스 로그에서 예기치 않거나 권한이 없는 활동을 모니터링합니다.
- 더 이상 필요하지 않은 사용되지 않는 엔드포인트, 권한, 애플리케이션 등록 및 역할 할당을 제거합니다.
기술 세트 구성에 대한 액세스 제한
기술 세트를 만들거나 수정하거나 실행할 수 있는 사용자는 대상 엔드포인트와 사용자 지정 Web API 기술에서 사용하는 인증 구성을 모두 제어할 수 있습니다. 이러한 권한을 신뢰할 수 있는 관리자로 제한하고 관리 ID 사용 사용자 지정 기술을 구성할 때 표준 변경 관리 및 보안 검토 프로세스를 따릅니다.
Important
값은 authResourceId 액세스 토큰에 대해 의도한 받는 사람 애플리케이션을 식별합니다. 지정된 uri 엔드포인트가 해당 애플리케이션에 대한 토큰을 수신하고 유효성을 검사해야 하는 엔드포인트인지 확인합니다. 구성이 잘못되면 인증 실패 또는 요청이 의도하지 않은 엔드포인트로 전송될 수 있습니다.