코드를 사용하여 데스크톱 흐름 작업
개발자는 프로그래밍 방식으로 데스크톱 흐름을 트리거하고 취소하는 것을 포함하여 데스크탑 흐름 기능을 애플리케이션에 추가할 수 있습니다. 이러한 기능은 Microsoft Dataverse 플랫폼의 일부로 제공됩니다.
전제 조건
- Dataverse 웹 API, Dataverse로 인증 및 Dataverse에서 OAuth 사용에 대한 지식.
- Dataverse 환경 및 조직 개념, 수동 또는 프로그래밍 방식으로 조직 URL을 검색하는 방법에 대한 지식.
- 데스크톱 흐름 개념 및 연결이 무엇이며 어떻게 만드는지에 대한 지식.
Important
이 문서에서는 URL 및 입력/출력 데이터의 모든 대괄호[...]를 시나리오에 특정한 값으로 바꿔야 합니다.
사용 가능한 데스크톱 흐름 목록
모든 데스크톱 흐름 스크립트는 워크플로 엔터티의 일부로 Dataverse에 있습니다.
범주를 기반으로 워크플로 목록을 필터링하여 데스크톱 흐름을 식별합니다.
데스크톱 흐름 가져오기 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1
데스크톱 흐름 가져오기 요청에 대한 응답
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
"value": [
{
"@odata.etag": "W1069462",
"name": "Desktop flow 1",
"workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
},
{
"@odata.etag": "W1028555",
"name": "Desktop flow 2",
"workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
}
]
}
데스크톱 흐름에 대한 스키마 가져오기
입력 및/또는 출력에 대한 흐름 스키마를 검색해야 하는 경우 대상 워크플로에 대해 clientData 필드를 사용할 수 있습니다.
데스크톱 흐름에 대한 스키마 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/clientdata/$value HTTP/1.1
데스크톱 흐름 스키마 가져오기 요청에 대한 응답
{
"clientversion": "2.19.00170.22097",
"properties": {
"definition": {
"dependencies": [],
"isvalid": true,
"name": "Desktop Flow 1",
"package": "UEsDBBQAAAAIAIqZlF...",
"$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#"
},
"inputs": {
"schema": {
"properties": {
"Input1": {
"default": "",
"description": "",
"format": null,
"title": "Input 1",
"type": "string",
"value": "0"
},
"Input2": {
"default": "",
"description": "",
"format": null,
"title": "Input2",
"type": "string",
"value": ""
}
},
"type": "object"
}
},
"outputs": {
"schema": {
"properties": {
"Output1": {
"default": "",
"description": "",
"format": null,
"title": "Output",
"type": "string",
"value": null
}
},
"type": "object"
}
}
},
"schemaversion": "ROBIN_20211012",
"targets": {
"schema": {
"properties": {},
"type": "object"
}
}
}
데스크톱 흐름 실행 상태 가져오기
Dataverse는 모든 데스크톱 흐름 실행을 flowsession 엔터티에 저장합니다.
데스크톱 흐름 실행 상태 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1
데스크톱 흐름 실행 상태에 대한 응답
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
"@odata.etag": "W1276122",
"statuscode": 8,
"statecode": 0,
"startedon": "2022-06-16T12:54:40Z",
"completedon": "2022-06-16T12:57:46Z",
}
데스크톱 흐름 출력 가져오기
데스크톱 흐름에 출력이 있는 경우 출력 필드를 쿼리하여 검색할 수 있습니다.
데스크톱 흐름 출력 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1
데스크톱 흐름 출력 요청에 대한 응답
{
"Output1": "My output value"
}
데스크톱 흐름 실행 트리거
Dataverse를 사용하여 애플리케이션을 통해 데스크톱 흐름을 트리거하는 기능을 추가할 수 있습니다. 이 기능을 구현하려면 RunDesktopFlow 작업을 사용해야 합니다.
작업을 호출하려면 다음 정보가 필요합니다.
실행하려는 데스크톱 흐름의
ID. 이 ID는 이 문서 앞부분의 사용 가능한 데스크톱 흐름 목록 섹션에서 설명한 대로 API를 통해 얻을 수 있습니다.Tip
또는 Power Automate의 데스크톱 흐름 세부 정보 URL에서 수동으로 ID를 검색할 수 있습니다. URL 형식은
https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details입니다.자세한 내용은 데스크톱 흐름 관리를 참조하십시오.
흐름을 실행하는 데 사용할 데스크톱 흐름 연결(머신/머신 그룹을 대상으로 함)의
name입니다. 이름은 Power Automate의 동일한 연결 페이지의 URL에서 검색할 수 있습니다. URL 형식은
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name]입니다.Note
자세한 내용은 데스크톱 흐름 연결 만들기를 참조하십시오.
Tip
또는 연결 이름 대신 연결 참조의 논리적 이름을 연결의 입력으로 사용할 수 있습니다(아래에 설명된 사용 예). 연결 참조는 Dataverse 테이블 연결 참조에 저장되며 사용 가능한 데스크톱 흐름 나열 섹션에 자세히 설명된 데스크톱 흐름과 동일한 방식으로 프로그래밍 방식으로 나열할 수 있습니다.
자세한 내용은 솔루션에서 연결 참조 사용 및 연결 참조 테이블/엔터티 참조를 참조하십시오.
데스크톱 흐름 트리거 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1
{
"runMode": "attended",
"runPriority": "normal",
"connectionName": "[Connection Name]",
"timeout": 7200,
"inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}
연결 참조를 통한 데스크톱 흐름 트리거 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1
{
"runMode": "attended",
"runPriority": "normal",
"connectionName": "[Connection Reference Logical Name]",
"connectionType": 2,
"timeout": 7200,
"inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}
데스크톱 흐름을 트리거하라는 요청의 응답
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
"flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}
Warning
API를 사용할 때 알아야 할 몇 가지 제한 사항이 있습니다.
API를 사용하여 데스크톱 흐름 실행을 트리거할 때 스크립트의 입력은 Power Automate 포털의 실행 세부 정보 페이지에서 볼 수 없습니다.
실행을 나타내는 흐름 세션의 담당자는 데스크톱 흐름을 나타내는 워크플로 엔터티의 담당자에 매핑됩니다. "사용자" 권한이 있는 워크플로에서 API를 호출하는 경우 몇 가지 제한 사항이 있습니다. 실행을 취소하고 상태를 쿼리하는 것은 흐름 세션에 대한 권한 누락으로 인해 차단될 수 있습니다.
Dataverse 가장은 지원되지 않습니다.
스크립트 완료 알림 수신
선택적 매개 변수 "callbackUrl"은 RunDesktopFlow 작업의 본문에서 사용할 수 있습니다. 스크립트 완료 알림을 받고 싶을 때 사용할 수 있습니다. 스크립트가 완료되면 POST 요청이 제공된 URL로 전송됩니다.
콜백 끝점에서 받은 요청
User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]
POST [yourCallbackURL]
{
"statuscode": 4,
"statecode": 0,
"startedon": "2022-09-05T08:04:11Z",
"completedon": "2022-09-05T08:04:41Z",
"flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}
콜백 URL 매개 변수가 제공되지 않으면 Dataverse에서 흐름 세션 상태를 폴링해야 합니다(데스크톱 흐름 실행 상태 가져오기 참조).
Note
- 콜백 URL 매개 변수를 제공하더라도 상태 폴링을 대체 메커니즘으로 계속 사용할 수 있습니다.
- 콜백 끝점 작업은 멱등원이어야 합니다.
- 끝점이 서버 오류 응답(코드 500 이상) 또는 "요청 시간 초과" 응답(코드 408)으로 응답하는 경우 POST 요청은 1초 간격으로 세 번 재시도됩니다.
콜백 URL 매개 변수 요구사항
서버에 현재 TLS 및 암호 제품군이 있어야 합니다.
HTTPS 프로토콜만 허용됩니다.
localhost(루프백)에 대한 액세스는 허용되지 않습니다.
IP 주소는 사용할 수 없습니다. DNS 이름 확인이 필요한 명명된 웹 주소를 사용해야 합니다.
서버는 AzureCloud 서비스 태그에 지정된 Power Platform 및 Dynamics 365 서비스 IP 주소 값의 연결을 허용해야 합니다.
Tip
콜백 호출이 인증되지 않았으므로 몇 가지 예방 조치를 취해야 합니다
- 콜백 알림 수신 시 흐름 세션 ID 유효성을 확인합니다. Dataverse는 진실의 원천입니다.
- 서버 측에서 속도 제한 전략을 구현하십시오.
- 여러 조직 간의 콜백 URL 공유를 제한하십시오.
데스크톱 흐름 실행 취소
트리거 기능과 유사하게 대기 중/실행 중인 데스크톱 흐름을 취소할 수도 있습니다. 데스크톱 흐름을 취소하려면 CancelDesktopFlowRun 작업을 사용하십시오.
데스크톱 흐름 실행 취소 요청
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1
데스크톱 흐름 취소 요청의 응답
HTTP/1.1 204 No Content
오류
오류가 발생하면 응답은 Dataverse 오류 메시지와 일치하는 다른 형식을 갖습니다. Http 오류 코드와 메시지는 문제를 이해하기에 충분한 정보를 제공해야 합니다.
HTTP/1.1 403 Forbidden
{
"error": {
"code": "0x80040220",
"message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
}
}
Note
귀사의 설명서 언어 기본 설정에 대해 말씀해 주시겠습니까? 간단한 설문 조사에 응해주세요. (이 설문 조사는 영어로 되어 있습니다.)
이 설문 조사는 약 7분 정도 걸립니다. 개인 데이터는 수집되지 않습니다(개인정보처리방침).
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기