커넥터 문자열 지침

  • 아티클

다음 문서에는 Power Automate, Power Apps 및 Logic App의 커넥터 내 문자열 필드에 대한 일반 지침이 포함되어 있습니다.

커넥터 정보

각 커넥터에는 커넥터 이름인 제목과 커넥터를 설명하는 설명이 있어야 합니다. 이 정보는 OpenAPI 정의(apiDefinition.swagger.json 파일 내)의 정보 섹션에 있는 제목 및 설명 필드에서 지정되어야 합니다.

커넥터 제목 및 설명에 대해 최소한 다음 지침을 따라야 합니다.

  • 커넥터 제목의 길이는 최대 30자입니다.
  • 커넥터 제목과 설명에는 API 단어를 포함할 수 없습니다.
  • 커넥터 제목 및 설명은 Power Platform 제품 또는 사용자가 백엔드 API를 가지고 있지 않은 제품은 참조할 수 없습니다.

인증된 커넥터에 적용되는 고급 표준 제목 및 설명 필드 지침은 여기에서 찾을 수 있으며 모범 사례로 사용해야 합니다.

작업

OpenAPI 정의에서 각 경로와 동사는 작업에 해당합니다. 아래 각 문자열/태그로 작업을 적절하게 설명하면 최종 사용자가 해당 작업을 올바르게 사용하는 데 도움이 됩니다. 작업에 대한 일부 문자열 필드는 다음과 같습니다.

  • 요약 : 작업 이름으로 표시됩니다.

    • 사례: 문장
    • 참고:
      • 이름에 슬래시( '/')가 없어야 합니다.
      • 80자를 초과하지 않아야 합니다.
      • 구두점 또는 공백 등 영숫자가 아닌 문자로 끝나서는 안 됩니다.

  • 설명: 다음 이미지와 같이, 정보 버튼 정보 버튼을 보여주는 스크린샷.을 선택하면 작업 설명으로 표시됩니다.

    • 사례: 문장.
    • 참고: 텍스트 상자에 맞게 짧게 유지합니다. 한 단어의 경우 마침표가 필요하지 않습니다.

  • operationId: 작업과 연결된 고유한 ID입니다.

    • 사례: Camel(공백이나 구두점 없음).
    • 참고: 작업의 의미를 전달합니다(예: GetContacts 또는 CreateContact).

    다음 이미지는 워크플로를 만드는 동안_요약_—이메일 전송 및_설명_—이 작업에서 이메일 메시지를 전송 필드가 표시되는 방식을 보여줍니다.

    요약 및 설명 필드가 표시되는 방식을 보여주는 스크린샷.

트리거 대 작업

트리거는 워크플로 또는 프로세스를 시작합니다. "매주 월요일 오전 3시에 워크플로 시작", "개체를 만드는 경우" 등을 예로 들 수 있습니다.

트리거 요약 및 설명 필드는 사람이 읽을 수 있어야 하고 의미가 있어야 합니다. 요약 트리거는 일반적으로 "__________________ 일 때" 형식입니다.

예:

트리거 요약
만들기 작업이 만들어질 때
엽데이트 작업이 업데이트될 때
삭제됨 작업이 삭제될 때

설명 트리거는 대개 "이 작업은 _______________ 일 때 트리거됩니다" 형식입니다.

예:

  • 이 작업은 새 작업이 추가될 때 트리거됩니다.

조치는 워크플로 내에서 완료할 작업입니다(예: "이메일 보내기", "행 업데이트", "알림 보내기" 등). 요약 작업에 대한 몇 가지 예는 아래와 같습니다.

작업 요약
만들기 새 작업 만들기
읽음 ID로 작업 가져오기
엽데이트 개체 업데이트
삭제됨 개체 삭제
목록 모든 개체 나열

매개 변수

각 작업(트리거 또는 조치)마다 사용자가 입력을 제공하는 매개 변수가 있습니다. 매개 변수에 중요한 일부 문자열 필드는 다음과 같습니다.

  • x-ms-summary: 매개 변수 이름으로 표시됩니다.

    • 사례: 제목
    • 참고: 제목은 80자로 제한됩니다.

  • 설명: 입력란에 매개 변수 설명으로 표시됩니다.

    • 사례: 문장
    • 참고: 텍스트 상자에 맞게 짧게 유지합니다. 한 단어의 경우 마침표가 필요하지 않습니다.

    아래 표시된 이미지에서 강조 표시된 매개 변수에는 x-ms-요약 필드에 대한 값으로 "제목", _설명_으로 "이메일의 제목 지정"이 있습니다.

    인터페이스의 x-ms-요약 및 설명 매개변수 값을 보여주는 스크린샷.

응답

각 작업마다 후속 작업에 대한 입력으로 워크플로에서 나중에 사용할 수 있는 응답이 있습니다. 결과 스키마는 여러 속성으로 구성됩니다. 각 속성에 중요한 일부 문자열 필드는 다음과 같습니다.

  • x-ms-summary: 결과 속성 이름으로 표시됩니다.

    • 사례: 제목
    • 참고: 짧은 이름을 사용하십시오.

  • 설명: 결과 속성에 대한 설명으로 표시됩니다.

    • 사례: 문장
    • 참고: 짧고 간결해야 하며, 끝에 마침표가 있어야 합니다.

    아래 이미지에서 워크플로의 후속 작업 중 하나에 동적 컨텐츠를 추가하려고 하면 "흐름 수동 트리거" 작업의 결과 스키마가 표시됩니다. 여기에서 "사용자 이메일"은 _x-ms-요약_이고 "수동으로 흐름 트리거" 작업의 응답으로 속성에 대한 _설명_에서 아래 표시되는 텍스트입니다.

응답

요약/x-ms-요약 및 설명 필드에 대해 일반적으로 고려해야 할 몇 가지 중요 참고 사항은 다음과 같습니다.

  • 요약 및 설명 텍스트는 동일하지 않아야 합니다.
  • 설명은 출력 형식 또는 속성과 관련된 개체 등, 사용자에게 추가 정보를 제공하기 위해 사용되어야 합니다. 예를 들면 다음과 같습니다. 요약 : ID, 설명: 사용자 ID
  • 중첩 값이 있는 개체의 경우 상위 이름의_x-ms-summary_가 하위 항목에 추가됩니다.

x-ms-visibility

엔터티의 표시 우선 순위를 결정합니다. 지정된 가시성이 없는 경우에는 "기본" 가시성으로 고려합니다. 가능한 값은 "중요", "고급" 또는 "내부"입니다. '내부'로 표시된 엔터티는 사용자 인터페이스에 표시되지 않습니다.

적용 대상:

  • 작업
  • 매개 변수
  • 응답 속성

예:

UI에서 "중요"로 표시된 엔터티는 맨 처음 표시되고, "고급"으로 표시된 것은 토글(강조 표시) 아래에 숨겨져 있으며, "내부"로 표시된 것들은 표시되지 않습니다. 다음 이미지는 "중요"로 표시된 매개 변수가 기본적으로 표시되는 예입니다. 또한 고급 옵션 표시 단추를 선택하면 "고급"으로 표시된 매개 변수가 표시됩니다.

고급 옵션의 드롭다운 목록을 보여주는 스크린샷.

확장한 숨겨진 고급 옵션을 보여주는 스크린샷.

피드백 제공

커넥터 플랫폼 관련 문제 또는 새로운 기능 아이디어에 대한 피드백을 주셔서 정말 감사합니다. 피드백을 제공하려면 문제 제출 또는 커넥터 관련 도움말 보기로 이동하여 피드백 유형을 선택하십시오.