팁
권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.
일부 API는 권한 부여에 API 키를 사용합니다. API 키는 클라이언트가 인증하고 액세스 권한을 얻기 위해 API 요청에 포함하는 공유 비밀입니다. API 플러그인은 다음 세 가지 방법으로 API 키 전송을 지원합니다.
- 헤더의
Authorization전달자 토큰으로 - 사용자 지정 헤더의 값으로
- 쿼리 매개 변수로 사용
참고
선언적 에이전트 작업의 경우 API 키 인증은 MCP 플러그인이 아닌 OpenAPI 문서에서 빌드된 API 플러그인에 적용됩니다. 에이전트의 MCP 플러그 인의 경우 OAuth 2.0(동적 클라이언트 등록 포함) 또는 Microsoft Entra SSO를 사용합니다. 패키지 수준 원격 MCP 연결은 다른 구성을 사용합니다. 앱 매니페스트의 인증을 참조하세요.
OpenAPI 문서에 API 키를 추가하고 API 키 인증 구성을 만드는 두 단계로 API 키 인증을 구성합니다.
1단계: OpenAPI 문서에 API 키 추가
Microsoft 365 Copilot은 OpenAPI 문서의 항목에 securitySchemes 따라 API 키를 보내는 방법을 결정합니다.
전달자 토큰
API에서 API 키를 전달자 토큰으로 수락하는 경우 OpenAPI 문서에서 전달자 인증을 활성화합니다. 자세한 내용은 소지자 인증을 참조하세요.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
사용자 지정 헤더
API가 사용자 지정 헤더의 API 키를 허용하는 경우 속성을 헤더 header 이름으로 설정하여 inname OpenAPI 문서에서 API 키 인증을 활성화합니다. 자세한 내용은 API 키를 참조하세요.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
쿼리 매개 변수
API가 쿼리 매개 변수에서 API 키를 허용하는 경우 속성을 query 쿼리 매개 변수의 이름으로 설정 in 하여 name OpenAPI 문서에서 API 키 인증을 사용하도록 설정합니다. 자세한 내용은 API 키를 참조하세요.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
2단계: API 키 인증 구성 만들기
API 키 인증은 플러그 인이 API를 호출할 때 Microsoft 365 Copilot이 API 키를 보내는 데 사용하는 Microsoft Enterprise 토큰 저장소에 저장된 레코드인 인증 구성(인증 구성)을 사용합니다. 지원되는 프로 코드 프로젝트에 대해 WIQD로 시작합니다. 도구 키트 및 Microsoft Teams 개발자 포털 절차를 대안으로 계속 사용할 수 있습니다. 선언적 에이전트 개발자 기술은 MCP 플러그 인을 빌드하기 때문에 API 키 인증을 지원하지 않습니다.
Work IQ Dev 도구 사용(권장)
기존 API 플러그인 매니페스트의 경우 , 및 --auth-name--auth-type api-key와 함께 --plugin-manifest사용합니다wiqd agent add auth. OpenAPI 보안 체계의 이름으로 또는 및 로 --api-key-name 설정합니다 --api-key-inheader.query API에서 해당 키를 전달자 토큰으로 대신 수락하는 경우 를 선택합니다 --auth-type bearer-token.
OpenAPI 문서 wiqd agent add action 에서 작업을 추가할 때 API 키 또는 전달자 자격 증명을 수락 --api-key 합니다. 이 명령은 값이 생략될 때 환경 자리 표시자를 문서화합니다. 선택한 명령의 자격 증명 처리를 따라 프로젝트의 프로비저닝 워크플로를 완료합니다. 이러한 API 키 옵션은 에이전트의 MCP 플러그인에 대한 API 키 지원을 설정하지 않습니다.
Microsoft 365 에이전트 도구 키트 사용
Microsoft 365 에이전트 도구 키트의 기존 OpenAPI 문서에서 API 플러그 인을 만들면 도구 키트가 API 키를 등록하고 인증 구성을 만들고 플러그 인 매니페스트를 업데이트합니다. OpenAPI 문서에서 속성을 정의 securitySchemes 해야 합니다.
Teams 개발자 포털 사용
에이전트 도구 키트를 사용하는 경우 Teams 개발자 포털에 등록하는 것은 선택 사항입니다. 인증 구성을 수동으로 생성하거나 Agents Toolkit에서 이미 생성한 인증 구성을 관리하는 데 사용합니다.
Teams 개발자 포털을 엽니다. 도구 ->API 키 등록을 선택합니다.
기존 등록이 없는 경우 API 키 만들기를 선택합니다. 기존 등록이 있는 경우 새 API 키를 선택합니다.
비밀 추가를 선택하고 API 키를 입력합니다.
다음 필드를 입력합니다.
- API 키 이름: 등록을 위한 식별 이름입니다.
-
기본 URL: API의 기본 URL입니다. 이 값은 OpenAPI 문서의 배열에 있는
servers항목에 해당해야 합니다. - 대상 테넌트: 홈 테넌트에 대한 API 액세스를 제한하거나 모든 테넌트를 허용합니다.
- 대상 Teams 앱: 최종 앱 ID를 모르는 경우 모든 Teams 앱을 선택합니다. 앱을 게시한 후 이 등록을 게시된 앱 ID와 바인딩합니다.
저장을 선택합니다.
등록을 완료하면 인증 구성 ID (현재 Teams 개발자 포털에서 레이블이 지정된 API 키 등록 ID )가 생성됩니다.
플러그 인 매니페스트에 인증 구성 ID 추가
Teams 개발자 포털에서 수동으로 인증 구성을 만들 때 런타임 인증 개체의 속성을 로 설정 type 하고 ApiKeyPluginVault인증 구성 ID로 설정합니다reference_id. 에이전트 도구 키트가 이를 수행합니다.
"auth": {
"type": "ApiKeyPluginVault",
"reference_id": "auth config ID"
},