OpenAPI 정의에서 사용자 지정 커넥터 만들기

아티클
04/19/2024

참고

이 항목은 Azure Logic Apps, Microsoft Power Automate 및 Microsoft Power Apps에서 사용자 지정 커넥터를 만들고 사용하는 방법에 대한 자습서 시리즈의 일부입니다. 프로세스를 이해하려면 사용자 지정 커넥터 개요를 읽으십시오.

사용자 지정 커넥터를 만들려면 커넥터에서 API의 작업 및 데이터 구조를 인식할 수 있도록 연결하려는 API를 설명해야 합니다. 이 토픽에서는 Cognitive Services Text Analytics Sentiment API(이 시리즈의 예)를 설명하는 OpenAPI 정의를 사용하여 사용자 지정 커넥터를 만듭니다.

API를 설명하는 또 다른 방법은 처음부터 사용자 지정 커넥터 만들기를 참고하세요.

전제 조건

예시 API를 설명하는 OpenAPI 정의입니다. 사용자 지정 커넥터를 생성할 때 OpenAPI 정의는 1MB 미만이어야 합니다. OpenAPI 정의는 OpenAPI 2.0(이전의 Swagger) 형식이어야 합니다.

보안 정의가 여러 개인 경우 사용자 지정 커넥터는 최상위 보안 정의를 선택합니다. 사용자 지정 커넥터 생성은 OAuth 보안 정의에서 클라이언트 자격 증명(예: 애플리케이션 및 암호)을 지원하지 않습니다.
Cognitive Services Text Analytics API에 대한 API 키.
다음 구독 중 하나:
- Azure, 논리 앱을 사용하는 경우
- Power Automate
- Power Apps
Logic Apps를 사용하는 경우 먼저 Azure Logic Apps 사용자 지정 커넥터를 만듭니다.

OpenAPI 정의 가져오기

이제 다운로드한 OpenAPI 정의로 작업할 준비가 되었습니다. 필요한 모든 정보가 정의에 포함되어 있으며 사용자 지정 커넥터 마법사를 진행하면서 이 정보를 검토하고 업데이트할 수 있습니다.

먼저 Logic Apps 또는 Power Automate 및 Power Apps용 OpenAPI 정의를 가져옵니다.

참고

OpenAPI 정의는 OpenAPI 2.0(이전의 Swagger) 형식이어야 합니다. OpenAPI 3.0 형식의 OpenAPI 정의는 지원되지 않습니다.

Logic Apps용 OpenAPI 정의 가져오기

Azure Portal로 이동하여 Azure Logic Apps 사용자 지정 커넥터 만들기의 앞부분에서 만든 Logic Apps 커넥터를 엽니다.
커넥터 메뉴에서 Logic Apps 커넥터를 선택한 다음 편집을 선택합니다.
일반에서 OpenAPI 파일 업로드를 선택한 다음, 만든 OpenAPI 정의로 이동합니다.

참고

이 자습서는 REST API에 중점을 두지만 Logic Apps와 함께 SOAP API를 사용할 수도 있습니다.

Power Automate 및 Power Apps용 OpenAPI 정의 가져오기

Power Apps 또는 Power Automate에 로그인합니다.
왼쪽 창에서 데이터 > 사용자 지정 커넥터을 선택합니다.
새 사용자 지정 커넥터를 선택한 다음, OpenAPI 파일 가져오기를 선택합니다.
사용자 지정 커넥터의 이름을 입력한 다음 다운로드했거나 생성된 OpenAPI 정의로 이동하고 계속을 선택합니다.

매개 변수 값

사용자 지정 커넥터 제목 SentimentDemo

매개 변수	값
사용자 지정 커넥터 제목	SentimentDemo

일반 세부 정보 검토

이 시점에서 Power Automate UI가 표시되지만, 단계는 3개 기술 전체에서 거의 동일합니다. 차이점을 지적하겠습니다. 주제의 이 부분에서는 주로 UI를 검토하고 값이 OpenAPI 파일의 섹션에 어떻게 대응하는지 보여줍니다.

마법사 위쪽에서 이름이 SentimentDemo로 설정되어 있는지 확인한 다음, 커넥터 만들기를 선택합니다.
일반 페이지에서 API에 대한 API 호스트 및 기준 URL을 포함하여 OpenAPI 정의에서 가져온 정보를 검토합니다. 커넥터는 API 호스트와 기본 URL을 사용하여 API를 호출하는 방법을 결정합니다.

참고

온-프레미스 API에 연결에 대한 자세한 내용은 데이터 게이트웨이를 사용하여 온-프레미스 API에 연결을 참조하십시오.

OpenAPI 정의의 다음 섹션에는 UI의 이 페이지에 대한 정보가 포함되어 있습니다.
```
  "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]
```

검토 인증 유형

사용자 지정 커넥터의 인증에는 여러 가지 옵션을 사용할 수 있습니다. Cognitive Services API는 API 키 인증을 사용하므로 OpenAPI 정의에 지정되어 있습니다.

보안 페이지에서 API 키의 인증 정보를 검토합니다.

API 키 매개 변수.

누군가가 사용자 지정 커넥터와 처음 연결하면 레이블이 표시됩니다. 편집을 선택하고 이 값을 변경할 수 있습니다. 매개변수 이름과 위치는 API가 예상하는 것과 일치해야 합니다(이 경우 Ocp-Apim-Subscription-Key 및 Header).

OpenAPI 정의의 다음 섹션에는 UI의 이 페이지에 대한 정보가 포함되어 있습니다.

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

커넥터 정의 검토

사용자 지정 커넥터 마법사의 정의 페이지는 커넥터가 작동하는 방식과 논리 앱, 흐름 및 앱에서 커넥터가 노출되는 방식을 정의하기 위한 다양한 옵션을 제공합니다. UI에 대해 설명하고 이 섹션의 몇 가지 옵션을 다루지만 직접 탐색해 보는 것도 좋습니다. 이 UI에서 처음부터 개체를 정의하는 방법에 대한 자세한 내용은 커넥터 정의 만들기를 참조하십시오.

다음 영역에는 모든 작업, 트리거(Logic Apps 및 Power Automate용) 및 커넥터에 대해 정의된 참조가 표시됩니다. 이 경우 OpenAPI 정의의 DetectSentiment 작업이 표시됩니다. 이 커넥터에는 트리거가 없지만, Azure Logic Apps 및 Power Automate에서 웹후크 사용에서 사용자 지정 커넥터에 대한 트리거를 알아볼 수 있습니다.
일반 영역에는 현재 선택된 작업 또는 트리거에 대한 정보가 표시됩니다. 여기서는 논리 앱이나 흐름의 작업 및 매개 변수에 대한 표시 유형 속성을 포함한 정보를 편집할 수 있습니다.
- 없음: 일반적으로 논리 앱 또는 흐름에 표시됩니다.
- 고급: 추가 메뉴 아래에 숨겨져 있습니다.
- 내부: 사용자에게 표시되지 않습니다.
- 중요: 사용자에게 항상 먼저 표시
요청 영역은 OpenAPI 정의에 포함된 HTTP 요청을 기반으로 정보를 표시합니다. 이 경우 HTTP 동사는 POST이고 URL은 /text/analytics/v2.0/sentiment입니다(API의 전체 URL은 <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). 본문 매개 변수를 더 자세히 살펴 보겠습니다.

OpenAPI 정의의 다음 섹션에는 UI의 일반 및 요청 영역에 대한 정보가 포함되어 있습니다.
```
"paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"
```
응답 영역은 OpenAPI 정의에 포함된 HTTP 응답을 기반으로 정보를 표시합니다. 이 경우 정의된 유일한 응답은 200(성공적인 응답)이지만 추가 응답을 정의할 수 있습니다.

OpenAPI 정의의 다음 섹션에는 응답과 관련된 일부 정보가 포함되어 있습니다.
```
"score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}
```
이 섹션은 커넥터에 의해 반환되는 두 가지 값인 id 및 score를 보여줍니다. 여기에는 데이터 유형과 OpenAPI 확장인 x-ms-summary 필드가 포함됩니다. 이 확장 기능 및 기타 확장 기능에 대한 자세한 내용은 사용자 지정 커넥터에 대한 OpenAPI 정의 확장을 참조하십시오.
유효성 검사 영역에는 API 정의에서 검색된 모든 문제가 표시됩니다. 커넥터를 저장하기 전에 이 영역을 확인해야 합니다.

정의 업데이트

다운로드한 OpenAPI 정의는 좋은 기본 예이지만, 누군가가 논리 앱, 흐름 또는 앱에서 커넥터를 사용할 때 더 친숙한 커넥터가 될 수 있도록 많은 업데이트가 필요한 정의를 사용할 수도 있습니다. 정의를 변경하는 방법을 보여드리겠습니다.

요청 영역에서 본문을 선택한 다음, 편집을 선택합니다.
매개 변수 영역에서 API에 필요한 세 가지 매개 변수인 ID, Language 및 Text가 표시됩니다. ID을 선택한 다음, 편집를 선택합니다.
스키마 속성 영역에서 매개 변수에 대한 설명을 업데이트한 다음, 뒤로를 선택합니다.

매개 변수 값

설명 제출하는 각 문서에 대한 숫자 식별자
매개 변수 영역에서 뒤로를 선택하여 기본 정의 페이지로 돌아갑니다.
마법사의 오른쪽 상단에서 커넥터 업데이트를 선택합니다.

매개 변수	값
설명	제출하는 각 문서에 대한 숫자 식별자

업데이트된 OpenAPI 파일 다운로드

OpenAPI 파일 또는 처음부터 사용자 지정 커넥터를 만들 수 있습니다(Power Automate 및 Power Apps 사용). 커넥터를 만드는 방법에 관계없이 서비스에서 내부적으로 사용하는 OpenAPI 정의를 다운로드할 수 있습니다.

Logic Apps의 사용자 지정 커넥터에서 다운로드합니다.
Power Automate또는 Power Apps의 사용자 지정 커넥터 목록에서 다운로드합니다.

커넥터 테스트

이제 커넥터를 만들었으므로 이를 테스트하여 제대로 작동하는지 확인합니다. 테스트는 현재 Power Automate 및 Power Apps에서만 사용할 수 있습니다.

중요

API 키를 사용하는 경우 커넥터를 생성한 직후에 커넥터를 테스트하지 않는 것이 좋습니다. 커넥터가 API에 연결할 준비가 될 때까지 몇 분이 걸릴 수 있습니다.

테스트 페이지에서 새 연결을 선택합니다.
Text Analytics API에서 API 키를 입력한 다음, 연결 만들기를 선택합니다.
테스트 페이지 로 돌아가서 다음 중 하나를 수행합니다.
- Power Automate에서 테스트 페이지로 다시 이동합니다. 새로 고침 아이콘을 선택하여 연결 정보가 업데이트되었는지 확인합니다.
- Power Apps의 경우 현재 환경에서 사용할 수 있는 연결 목록으로 이동합니다. 오른쪽 상단에서 기어 아이콘을 선택한 다음 사용자 지정 커넥터를 선택합니다. 만든 커넥터를 선택한 다음, 테스트 페이지로 돌아갑니다.
테스트 페이지에서 텍스트 필드에 대한 값을 입력하고(다른 필드는 이전에 설정한 기본값을 사용함), 테스트 작업을 선택합니다.
커넥터는 API를 호출하고 감정 점수가 포함된 응답을 검토할 수 있습니다.