처음부터 사용자 지정 커넥터 만들기
이 문서는 Azure Logic Apps, Microsoft Power Automate 및 Microsoft Power Apps에서 사용자 지정 커넥터를 만들고 사용하는 방법에 대한 자습서 시리즈의 일부입니다.
참고
프로세스를 이해하려면 사용자 지정 커넥터 개요를 읽으십시오.
사용자 지정 커넥터를 만들려면 커넥터에서 API의 작업 및 데이터 구조를 인식할 수 있도록 연결하려는 API를 설명해야 합니다. 이 토픽에서는 Azure Cognitive Services Text Analytics API 감정 작업(이 시리즈의 예)을 설명하기 위해 OpenAPI 정의를 사용하지 않고 처음부터 사용자 지정 커넥터를 만듭니다. 대신 사용자 지정 커넥터 마법사에서 커넥터를 자세히 설명합니다.
API를 설명하는 다른 방법을 보려면 OpenAPI 정의에서 사용자 지정 커넥터 만들기로 이동하세요.
참고
현재 Power Automate 및 Power Apps에서 처음부터 사용자 지정 커넥터를 만들 수 있습니다. Logic Apps의 경우 최소한 기본 OpenAPI 정의로 시작해야 합니다.
전제 조건
Cognitive Services Text Analytics API에 대한 API 키
다음 구독 중 하나:
사용자 지정 커넥터 마법사를 시작
Power Apps 또는 Power Automate에 로그인합니다.
왼쪽 창에서 데이터 > 사용자 지정 커넥터을 선택합니다.
새 사용자 지정 커넥터 > 처음부터 만들기를 차례로 선택합니다.
사용자 지정 커넥터의 이름을 입력한 다음, 계속을 선택합니다.
매개 변수 값 사용자 지정 커넥터 제목 SentimentDemo
1단계: 일반 세부 정보 업데이트
이 시점에서 Power Automate UI가 표시되지만, 단계는 기술 전체에서 거의 동일합니다. 차이점을 지적하겠습니다.
일반 탭에서 다음을 수행합니다.
설명 필드에서 의미 있는 값을 입력합니다. 이 설명은 사용자 지정 커넥터의 세부 정보에 나타나며 다른 사용자가 커넥터가 자신에게 유용한지 여부를 결정하는 데 도움이 될 수 있습니다.
호스트 필드를 Text Analytics API의 주소로 업데이트합니다. 커넥터는 API 호스트와 기본 URL을 사용하여 API를 호출하는 방법을 결정합니다.
매개 변수 값 Description Cognitive Services Text Analytics Sentiment API를 사용하여 텍스트가 긍정적인지 부정적인지 확인 Host westus.api.cognitive.microsoft.com
2단계: 인증 유형 지정
사용자 지정 커넥터의 인증에는 여러 가지 옵션을 사용할 수 있습니다. Cognitive Services API는 이 자습서에서 지정하는 대로 API 키 인증을 사용합니다.
보안 탭에서 인증 유형 아래의 API 키를 선택합니다.
API 키 아래에서 매개 변수 레이블, 이름 및 위치를 지정합니다. 사용자 지정 커넥터와 처음 연결할 때 표시되므로 의미 있는 레이블을 지정합니다. 매개 변수 이름 및 위치는 API가 예상하는 것과 일치해야 합니다. 연결을 선택합니다.
매개 변수 값 매개 변수 레이블 API 키 매개 변수 이름 Ocp-Apim-Subscription-Key 매개 변수 위치 헤더 마법사 위쪽에서 이름이 SentimentDemo로 설정되어 있는지 확인한 다음, 커넥터 만들기를 선택합니다.
3단계: 커넥터 정의 만들기
사용자 지정 커넥터 마법사는 커넥터가 작동하는 방식과 논리 앱, 흐름 및 앱에서 커넥터가 노출되는 방식을 정의하기 위한 다양한 옵션을 제공합니다. UI에 대해 설명하고 이 섹션의 몇 가지 옵션을 다루지만 직접 탐색해 보는 것도 좋습니다.
작업 만들기
가장 먼저 할 일은 Text Analytics API 감정 작업을 호출하는 작업을 만드는 것입니다.
정의 탭의 왼쪽 창에는 커넥터에 대해 정의된 모든 작업, 트리거(Logic Apps 및 Power Automate용) 및 참조가 표시됩니다. 새 작업를 선택합니다.
이 커넥터에는 트리거가 없습니다. 사용자 지정 커넥터에 대한 트리거에 대해 알아보려면 Azure Logic Apps 및 Power Automate에서 웹후크 사용으로 이동하십시오.
일반 영역에는 현재 선택된 작업 또는 트리거에 대한 정보가 표시됩니다. 이 작업에 대한 요약, 설명 및 작업 ID를 추가합니다.
매개 변수 값 요약 감지된 감정을 나타내는 숫자 점수 반환 설명 이 API는 0~1 사이의 숫자 점수를 반환합니다. 1에 가까운 점수는 긍정적인 정서를 나타내고, 0에 가까운 점수는 부정적인 정서를 나타냅니다. 작업 ID DetectSentiment 표시 속성을 없음 설정으로 둡니다. 논리 앱 또는 흐름의 작업 및 매개 변수의 이 속성에는 다음과 같은 옵션이 있습니다.
- 없음: 일반적으로 논리 앱 또는 흐름에 표시됩니다.
- 고급: 다른 메뉴 아래 숨겨짐
- 내부: 사용자에게 표시되지 않습니다.
- 중요: 사용자에게 항상 먼저 표시됩니다.
요청 영역에는 작업에 대한 HTTP 요청을 기반으로 정보가 표시됩니다. 샘플에서 가져오기를 선택합니다.
API 연결에 필요한 정보를 지정하고 요청 본문(다음 이미지 이후 제공)을 지정한 후 가져오기을 선택합니다. 이 정보를 제공하지만 공용 API의 경우 일반적으로 Text Analytics API(v2.0)와 같은 문서에서 이 정보를 얻습니다.
매개 변수 값 동사 게시 URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>Body 다음 JSON 코드 사용 예:
{ "documents": [ { "language": "string", "id": "string", "text": "string" } ] }응답 영역에는 작업에 대한 HTTP 응답을 기반으로 정보가 표시됩니다. 기본 응답 추가를 선택합니다.
응답 본문을 지정한 다음 가져오기를 선택합니다. 요청 본문에 대해 했던 것처럼 이미지에 따라 이 정보를 제공하지만 일반적으로 API 설명서에 제공됩니다.
예:
{ "documents": [ { "score": 0.0, "id": "string" } ], "errors": [ { "id": "string", "message": "string" } ] }유효성 검사 영역에는 API 정의에서 검색된 모든 문제가 표시됩니다. 상태를 확인한 다음 마법사의 오른쪽 상단에서 커넥터 업데이트를 선택합니다.
정의 업데이트
이제 누군가가 논리 앱, 흐름 또는 앱에서 커넥터를 사용하는 경우 커넥터를 더 쉽게 사용할 수 있도록 몇 가지 항목을 변경해 보겠습니다.
요청 영역에서 본문을 선택한 다음, 편집을 선택합니다.
매개 변수 영역에서 API에 필요한 세 가지 매개 변수인
id,language및text가 표시됩니다. id을 선택하고 편집를 선택합니다.스키마 속성 영역에서 매개 변수에 대한 값을 업데이트한 다음, 뒤로를 선택합니다.
매개 변수 값 Title ID Description 제출하는 각 문서에 대한 식별자 Default value 6 필수 네 매개 변수 영역에서 언어 > 편집을 선택한 후 다음 값을 사용하여 이 절차의 2단계와 3단계에서
id에 사용한 프로세스를 반복합니다.매개 변수 값 Title 언어 Description 텍스트에 대한 2 또는 4자 언어 코드 Default value en 필수 네 매개 변수 영역에서 텍스트 > 편집을 선택한 후 다음 값을 사용하여 이 절차의 2단계와 3단계에서
id에 사용한 프로세스를 반복합니다.매개 변수 값 제목 텍스트 설명 감정을 분석할 텍스트 기본값 없음 필수 네 매개 변수 영역에서 뒤로를 선택하면 기본 정의 탭으로 이동합니다.
마법사의 오른쪽 상단에서 커넥터 업데이트를 선택합니다.
4단계: (선택 사항) 커넥터를 AI 플러그인으로 활성화
커넥터를 인증하려는 경우에만 커넥터에 AI 플러그인(프리뷰) 탭을 사용하세요. 커넥터를 AI 플러그인으로 사용하려면 커넥터가 인증되어야 합니다.
커넥터를 AI 플러그인으로 활성화하기 전에 AI 플러그인 시나리오의 사용 사례를 이해하고 지원 가능성, 모범 사례 및 권장 사항과 같은 기타 고려 사항을 검토했는지 확인하십시오. 추가 정보: 커넥터 AI 플러그인 생성(프리뷰)
왼쪽 탐색 창에서 사용자 지정 커넥터를 선택합니다.
사용자 지정 커넥터가 표시되지 않으면 더보기 > 모두 검색 > 사용자 지정 커넥터를 선택합니다. 옵션이 왼쪽 탐색 창에 나타납니다.
오른쪽 상단에 있는 새 사용자 지정 커넥터 메뉴에서 옵션을 선택합니다.
AI 플러그인(프리뷰) 탭을 선택합니다.
플러그인 매니페스트 섹션에서 이 커넥터를 AI 플러그인으로 활성화하기 위한 세부 정보를 입력합니다.
필드 Description 플러그인 매니페스트: 이름 AI 플러그인의 이름입니다. 플러그인 매니페스트: 설명 AI 플러그인의 설명입니다. 추가 정보: 커넥터 AI 플러그인 생성(프리뷰) 플러그인 매니페스트: 이메일 연락처 이 AI 플러그인에 대한 연락처의 이메일 주소입니다. 플러그인 매니페스트: 법적 정보 URL AI 플러그인과 관련된 법적 정보가 게시되는 공개적으로 액세스 가능한 위치입니다. 플러그인 작업 세부 정보 섹션까지 아래로 스크롤하고 커넥터 AI 플러그인의 각 작업에 대한 작업 세부 정보를 입력합니다.
필드 Description 플러그인 작업 세부 정보: 요약 사용자가 수행할 수 있는 각 AI 플러그인 작업에 대한 요약입니다. 플러그인 작업 세부 정보: 설명 이 특정 AI 플러그인 작업 단계와 관련하여 사용자가 수행할 수 있는 각 작업에 대한 설명입니다. 확인란: Copilot 플러그인 작업으로 활성화 확인란에 확인 표시가 있으면 AI 플러그인 작업이 활성화됩니다. 확인란: 사용자 확인이 필요합니까? 확인란에 확인 표시가 있으면 사용자 확인이 필요합니다. 팁
작업을 정의하는 데 도움이 필요하면 Swagger 편집기 토글을 켜세요.
매개 변수 섹션까지 아래로 스크롤하고 커넥터 AI 플러그인에 대한 매개 변수 세부 정보를 입력합니다.
필드 Description 매개 변수: 이름 매개 변수의 이름입니다. ID 대신 계정 식별자 등 식별 가능한 이름을 사용하세요. 매개 변수: 설명 매개 변수의 설명입니다. b_date 대신 연락처에 대해 MM/DD/YYYY 형식 생년월일과 같은 설명적인 설명을 사용하세요. 이러한 이름과 설명은 LLM(대규모 언어 모델)이 AI 플러그인과 효과적으로 상호 작용하는 데 도움이 됩니다. 매개 변수: 요약 매개 변수에 대한 요약 정보입니다. 매개 변수: 기본값 매개 변수의 기본값입니다. AI 플러그인(프리뷰) 섹션 아래의 요청 섹션에서 입력 매개 변수를 선택한 후 설명을 입력합니다.
5단계: (선택 사항) 사용자 지정 코드 지원 사용
사용자 지정 코드는 기존 정책 템플릿의 범위를 넘어 요청 및 응답 페이로드를 변환합니다. 변환에는 추가 데이터를 가져오기 위한 외부 요청 전송이 포함됩니다. 코드가 사용되면 코드가 없는 정의보다 우선합니다. 이는 코드가 실행되고 요청을 백엔드로 보내지 않음을 의미합니다.
참고
- 이 단계는 선택 사항입니다. 이 단계를 무시하고 6단계: 커넥터 테스트로 이동하여 커넥터 생성을 위한 코드 없는 경험을 완료할 수 있습니다.
- 사용자 지정 코드 지원은 공개 프리뷰에서 사용할 수 있습니다.
코드를 붙여넣거나 코드와 함께 파일을 업로드할 수 있습니다. 코드는 다음을 충족해야 합니다.
- C#으로 작성되어야 합니다.
- 최대 실행 시간이 5초입니다.
- 파일 크기는 1MB 이하입니다.
코드 작성 지침 및 샘플을 보려면 사용자 지정 커넥터에 코드 작성으로 이동하세요.
사용자 지정 코드에 대한 자주 묻는 질문은 사용자 지정 코드 FAQ를 참조하세요.
코드 탭에서 다음 옵션 중 하나를 사용하여 사용자 지정 코드를 삽입합니다.
- 복사/붙여 넣기
- 업로드 버튼을 선택합니다.
사용자 지정 코드를 업로드하도록 선택하면 확장자가 .cs 또는 .csx인 파일만 사용할 수 있습니다.
중요
현재 코드 편집기에서 구문 강조만 지원합니다. 코드를 로컬에서 테스트해야 합니다.
코드를 붙여넣거나 업로드한 후 코드 비활성화 옆에 있는 토글을 선택하여 코드를 활성화합니다. 토글 이름이 코드 활성화됨으로 변경됩니다.
언제든지 코드를 활성화하거나 비활성화할 수 있습니다. 토글이 코드 비활성화됨이면 코드가 삭제됩니다.
드롭다운 메뉴에서 옵션을 선택하여 사용자 지정 코드에 적용할 작업 및 트리거를 선택합니다. 작업을 선택하지 않으면 작업과 트리거가 모든 작업에 적용됩니다.
6단계: 커넥터 테스트
이제 커넥터를 만들었으므로 이를 테스트하여 제대로 작동하는지 확인합니다. 테스트는 현재 Power Automate 및 Power Apps에서만 사용할 수 있습니다.
중요
API 키를 사용하는 경우 커넥터를 생성한 직후에 커넥터를 테스트하지 않는 것이 좋습니다. 커넥터가 API에 연결할 준비가 될 때까지 몇 분이 걸릴 수 있습니다.
테스트 탭에서 새로운 연결을 선택합니다.
Text Analytics API에서 API 키를 입력한 다음, 연결 만들기를 선택합니다.
참고
전달자 인증이 필요한 API의 경우 API 키 앞에 전달자와 공백 하나를 추가합니다.
테스트 탭으로 돌아가서 다음 중 하나를 수행합니다.
(Power Automate에서) 테스트 탭으로 다시 이동합니다. 연결 정보가 업데이트되었는지 확인하려면 새로 고침 아이콘을 선택하십시오.
(Power Apps에서) 현재 환경에서 사용할 수 있는 연결 목록으로 이동합니다. 왼쪽 창에서 데이터 > 사용자 지정 커넥터을 선택합니다. 생성한 커넥터를 선택한 다음 테스트 탭으로 돌아갑니다.
테스트 탭에서 텍스트 필드에 값을 입력하고(다른 필드는 이전에 설정한 기본값을 사용) 테스트 작업을 선택합니다.
커넥터는 API를 호출하고 감정 점수가 포함된 응답을 검토할 수 있습니다.
(CLI 사용자용) 모범 사례
모든 커넥터를 다운로드하고, Git 또는 다른 원본 코드 관리 시스템을 사용하여 파일을 저장합니다.
업데이트가 올바르지 않은 경우 원본 코드 관리 시스템에서 올바른 파일 세트로 update 명령을 다시 실행하여 커넥터를 다시 배포합니다.
먼저 테스트 환경에서 사용자 지정 커넥터와 설정 파일을 테스트한 후에 프로덕션 환경에 배포합니다.
항상 환경 및 커넥터 ID가 올바른지 다시 확인합니다.
다음 단계
이제 사용자 지정 커넥터를 만들고 해당 동작을 정의했으므로 다음에서 커넥터를 사용할 수 있습니다.
조직 외부의 사용자가 사용할 수 있도록 조직 내에서 커넥터를 공유하거나 커넥터 인증을 받을 수도 있습니다.
피드백 제공
커넥터 플랫폼 관련 문제 또는 새로운 기능 아이디어에 대한 피드백을 주셔서 정말 감사합니다. 피드백을 제공하려면 문제 제출 또는 커넥터 관련 도움말 보기로 이동하여 피드백 유형을 선택하십시오.