설정 출처

이 페이지는 Data Connection의 Webhooks와 관련된 상세한 설정 옵션 및 권한을 문서화합니다.

입력과 결과물 설정하기

각 웹훅은 입력 파라미터를 외부 시스템에 요청될 것으로 매핑하여 유연하게 설정할 수 있습니다. 그런 다음, 시스템으로부터의 응답은 Palantir Foundry의 다른 곳에서 사용될 수 있는 결과 파라미터로 캡처될 수 있습니다.

입력 파라미터

입력 파라미터는 사용자가 웹훅을 실행할 때 전달될 수 있는 입력을 나타냅니다. 일반적으로 웹훅은 액션 유형에서 사용하도록 설정되며, 여기서 액션 파라미터와 웹훅 입력 파라미터 사이의 매핑을 지정할 수 있습니다.

웹훅 입력 파라미터에는 많은 데이터 유형과 제약 조건이 사용 가능합니다:

• Boolean 파라미터는 true 또는 false일 수 있습니다.
• Integer, Long, Double 파라미터는 숫자 값으로 나타냅니다.
• 스트링 파라미터는 텍스트 값을 나타내며, 특정 값만 허용하도록 제한할 수 있습니다.
• 날짜 및 타임스탬프 파라미터는 시간 기반 데이터를 나타냅니다.

이 기본 유형 외에도 여러 컬렉션 유형을 사용할 수 있습니다:

• 리스트 파라미터는 특정 유형의 입력의 순서 있는 컬렉션을 나타냅니다.
• 레코드 파라미터를 사용하여 키/값 쌍을 전달할 수 있고, 특정 유형의 값과 함께 특정 키를 필요로하도록 제한할 수 있습니다.
• 옵션 파라미터는 존재할 수도 있고 없을 수도 있는 입력을 나타냅니다.

마지막으로, 업로드 된 파일을 전달하는 데 사용할 수 있는 첨부 파일 유형도 있습니다. 웹훅이 에이전트에서 실행되는 경우 첨부 파일이 지원되지 않는다는 점을 주의하세요.

출력 파라미터

출력 파라미터를 사용하면 외부 시스템에서 반환된 데이터를 Foundry의 다른 곳에서 사용하는 데 필요한 정보를 캡처할 수 있습니다. 예를 들어, 외부 시스템에서 새로운 레코드를 생성할 때, 시스템은 새 레코드에 대한 ID를 반환할 수 있습니다. 이 새로운 ID를 출력 파라미터에서 캡처함으로써, 이를 액션에 전파하고 즉시 Foundry 오브젝트에 기록할 수 있습니다.

단일 출력 파라미터인 unique_id에 대한 예제 설정이 아래의 웹훅 설정 마법사에서 보여집니다:

또한, 출력 파라미터는 웹훅 설정 단계에서 직접 접근할 수도 있습니다. 아래에 예시가 있습니다. 여기서 웹훅 호출은 이전 호출의 응답에서 값을 사용합니다. 첫 번째 웹훅 호출은 이렇게 응답을 반환합니다:

{
  "results": {
    "unique_id": "ID4567" // 고유한 ID (예: ID4567)
  }
}

두 번째 웹훅 호출을 구성합니다. Headers 탭에서는 @을 입력하여 이전 호출의 응답에서 값을 참조할 수 있는 메뉴를 열고 인라인 참조를 생성할 수 있습니다.

From a call을 선택하고 응답을 파싱할 이전 호출을 선택합니다. 응답에서 필요한 값을 추출하는 데 사용할 수 있는 세 가지 옵션은 다음과 같습니다.

• Whole response: 전체 응답을 문자열로 추출합니다.
• Extract by key: 응답의 키를 사용하여 필요한 값을 추출합니다.
• Extract by index: 인덱스 위치(영 인덱스)를 사용하여 배열 응답에서 필요한 값을 추출합니다.

아래 예제에서는 Extract by key를 선택하고 Add nested key 옵션을 사용하여 키를 구성합니다: results 다음에 unique_id가 오도록 합니다.

Add를 선택하면 헤더 값 필드에 참조가 표시됩니다.

캡처되는 결과물은 사용 중인 Task type에 따라 달라집니다.

REST 웹훅에서 결과물을 캡처하고 이러한 결과물을 액션에서 사용하는 방법에 대한 자세한 정보를 보려면 여기를 클릭하십시오.

편의를 위해 웹훅 작업의 결과는 특정 경우에 적절한 결과물 유형으로 자동 변환됩니다.

• 스트링 결과물이 구성되어 있고 웹훅 작업 결과가 문자열이 아닌 경우 결과는 JSON 문자열로 변환됩니다.
• 레코드 결과물이 구성되어 있고 웹훅 작업 결과가 문자열인 경우 웹훅 서비스에서 문자열을 JSON으로 구문 분석하려고 시도합니다.
• Double 결과물이 구성된 경우 웹훅 작업 결과가 정수 또는 롱인 경우 자동으로 변환됩니다.

"Test Connection" 사이드 패널을 통해 요청된 응답을 사용하여 결과물을 구성할 수 있습니다. 성공적인 테스트 요청이 이루어지면 응답에서 구문 분석된 제안 결과물이 새 결과물을 추가할 때 자동으로 표시됩니다.

Task body

일부 웹훅은 작업으로 구현됩니다. 이러한 웹훅의 경우 Task body는 웹훅이 실행될 때 작업에 전송될 데이터를 나타냅니다.

각 작업이 기대하는 구조는 해당 웹훅 유형 항목에 나열될 것이며, 해당 작업 유형에 따라 달라집니다. 작업 본문은 Handlebars 구문을 사용하여 정의해야 합니다. 작업 본문에서는 위에서 설명한 대로 웹훅에 정의한 입력값을 참조할 수 있습니다.

웹훅 유형

각 웹훅 유형은 다양한 구성 옵션을 지원합니다. 이 섹션에서는 다양한 웹훅 유형에 사용 가능한 옵션을 문서화하고 기본 예제를 제공하여 시작하는 데 도움이 됩니다.

REST API

웹훅의 가장 일반적인 사용은 REST API에 대한 HTTP 요청을 수행하는 것입니다. REST API 소스를 구성한 후 요청 빌더 인터페이스를 사용하여 원하는 요청을 구성할 수 있습니다.

REST API 소스에 사용 가능한 옵션은 다음과 같습니다.

다중 요청

단일 웹훅은 여러 요청을 포함할 수 있습니다. 요청은 연결되어 있으며 이전 호출의 응답값을 후속 호출에서 참조할 수 있습니다.

REST API (레거시)

magritte-rest-v2 소스를 설정한 후 generic-rest-webhook-task를 사용하여 REST 웹훅을 생성할 수 있습니다.

REST 웹훅의 경우 작업 본문 구조는 외부 시스템에 요청할 REST 요청을 나타내는 calls 배열이어야 합니다.

다음은 REST 웹훅의 기본 작업 본문 템플릿 예제로, 단일 HTTP 호출을 나타냅니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "calls": [
        {
            "type": "magritte-rest-call",
            // 매그리트 REST 호출 유형
            "method": "POST",
            // HTTP 메서드는 POST를 사용합니다.
            "requestMimeType": "application/json",
            // 요청 미디어 유형은 JSON입니다.
            "path": "your/request/path",
            // 여기에 요청 경로를 입력하세요.
            "body": { "text": {{json message}} }
            // 메시지를 JSON 형식으로 전송합니다.
        }
    ]
}

이 작업 본문 템플릿은 your/request/path 엔드포인트에 { text: <message> }의 요청 본문을 가진 POST 요청을 만듭니다. 여기서 <message>는 웹훅의 문자열 입력 파라미터입니다.

출력 파라미터 추출

REST 웹훅에서 출력 파라미터를 추출하는 두 가지 주요 방법이 있습니다: 1) 이름으로 JSON 응답에서 상위 수준 필드를 캡처, 2) 보다 맞춤화된 추출 로직을 위해 JSON 추출기를 정의하고 출력할 필드를 명시적으로 나열합니다.

또한 전체 응답 JSON을 문자열 출력으로 추출할 수도 있습니다. 이를 통해 후속 편집이나 함수를 사용한 알림 렌더링을 수행할 때 응답을 순회할 수 있는 추가 유연성을 제공합니다.

상위 수준 필드를 캡처하는 경우, 다음과 같은 응답을 반환하는 REST 호출을 구성했다고 가정해 보겠습니다:

Copied!
1
2
3
{
    "id": "c52fd6e4-6eb5-4da1-8908-4845e51c801b" // UUID 형식의 고유 식별자
}

JSON 응답에서 키로 사용하는 것과 동일한 ID를 가진 출력 파라미터를 정의하여 결과값을 캡처할 수 있습니다. 이 예시에서는 id라는 파라미터 ID를 가진 문자열 출력 파라미터를 추가하면 이 필드가 응답에서 캡처됩니다.

응답에서 중첩된 필드를 캡처해야 하는 경우, extractors를 지정하여 값을 추출할 수 있습니다. 추출된 값은 이후 호출에서도 연결하여 사용할 수 있습니다. 전체 응답을 캡처해야 하는 경우, 루트 경로를 대상으로 하는 extractors를 지정하여 전체 응답을 추출할 수 있습니다: "result": "/".

아래는 Task 본문 템플릿의 예시로, GET 엔드포인트에 대한 요청을 통해 데이터를 검색한 다음, 이전 호출에서 얻은 데이터를 사용하여 POST 엔드포인트에 요청을 보내는 경우입니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
    "calls": [
        {
            "type": "magritte-rest-call",
            // 매그리트 REST 요청 유형
            "method": "GET",
            // GET 메소드 사용
            "path": "path/to/fetchData",
            // 데이터를 가져올 경로
            "extractor": [
              {
                "type": "json",
                // JSON 추출기 사용
                "assign": {
                  "request_output": "/json/path/to/output"
                  // 출력 경로에 요청 결과 할당
                }
              }
            ]
        },
        {
            "type": "magritte-rest-call",
            // 매그리트 REST 요청 유형
            "method": "POST",
            // POST 메소드 사용
            "path": "your/request/path",
            // 요청 경로
            "body": { "text": {%request_output%} },
            // 본문에 이전 요청의 출력값 포함
            "extractor": [
              {
                "type": "json",
                // JSON 추출기 사용
                "assign": {
                  "result": "/json/path/to/result"
                  // 결과 경로에 추출된 값 할당
                }
              }
            ]
        }
    ],
    "output": ["result"]
    // 최종 결과 출력
}

첫 번째 호출은 path/to/fetchData의 엔드포인트에 GET 요청을 보내고, JSON 경로 /json/path/to/output에서 데이터를 추출하여 request_output이라는 상태 변수에 저장합니다. 그런 다음 두 번째 호출의 본문에서 request_output 상태를 사용합니다. 두 번째 호출에서 JSON 응답의 다른 필드를 result라는 상태 변수로 추출합니다. 마지막으로 설정의 "output" 필드는 어떤 추출된 필드가 결과물 매개 변수로 반환되어야 하는지를 정의합니다.

기타 옵션

calls 및 output을 지정하는 것 외에도 REST 웹훅 작업에 대해 사용할 수 있는 몇 가지 추가 구성 옵션이 있습니다.

• REST 웹훅에서 여러 호출을 수행하는 경우, 하나의 호출만이 안전하지 않은 HTTP 메서드를 사용할 수 있습니다. 외부 시스템의 상태를 수정할 수 있는 호출이 안전하지 않은 호출입니다. 기본적으로 GET, OPTIONS, HEAD 요청만이 안전한 것으로 간주됩니다. 호출의 필드로 "isHttpMethodSafe": true를 지정함으로써 다른 유형의 호출(예: POST 또는 PUT)의 안전성을 무시할 수 있습니다. 이는 이전 요청 중 하나가 POST이고 그것의 응답을 후속 요청에서 사용하는 경우와 같이 여러 요청을 수행할 때 유용할 수 있습니다.
• 재시도 가능한 HTTP 상태 코드를 나타내는 retryable-status-codes 배열을 지정할 수 있습니다.
  • 예를 들어, 서버에서 503 응답을 받을 때 외부 요청을 재시도하도록 웹훅을 구성할 수 있습니다. 이 옵션은 기본값으로 빈 목록입니다.
• 실패한 요청에도 불구하고 연결된 서버에서 데이터가 변경되지 않았음을 나타내는 external-system-not-changed-status-codes 배열을 지정할 수 있습니다.
  • 이 옵션은 기본적으로 400에서 431까지의 모든 상태 코드입니다.
  • 웹훅이 실행되어 실패하면 외부 시스템이 변경되었을 수 있는지 여부를 파악하여 쓰기 실패의 디버깅이 가능합니다.

Salesforce

Salesforce 웹훅에서 사용할 수 있는 작업 유형은 다음과 같습니다:

• create-record-salesforce-webhook-task: 주어진 유형의 Salesforce 레코드를 생성합니다.
• update-record-salesforce-webhook-task: 주어진 유형의 Salesforce 레코드를 업데이트합니다.
• delete-record-salesforce-webhook-task: Salesforce 레코드를 삭제합니다.
• composite-salesforce-webhook-task: Salesforce composite request를 사용하여 Salesforce 레코드를 수정합니다.

아래에는 각 작업 유형에 대한 작업 본문 예시가 있습니다.

create-record-salesforce-webhook-task

이 작업 유형은 Salesforce API에 해당합니다.

Copied!
1
2
3
4
5
6
7
8
{
  "record-type-name": "Account", // 계정
  "data": {
    "Name": {{json name}}, // 이름
    "Industry": {{json industry}}, // 산업
    "BillingCountry": {{json country}} // 청구 국가
  }
}

update-record-salesforce-webhook-task

이 작업 유형은 이 Salesforce API에 해당합니다.

Copied!
1
2
3
4
5
6
7
8
9
{
  "record-type-name": "Account", // 계정 유형 이름
  "record-id": {{json record-id}}, // 레코드 아이디
  "data": {
    "Name": {{json name}}, // 이름
    "Industry": {{json industry}}, // 산업
    "BillingCountry": {{json country}} // 청구 국가
  }
}

delete-record-salesforce-webhook-task

이 작업 유형은 Salesforce API에 해당합니다.

Copied!
1
2
3
4
{
  "record-type-name": "Account", // 레코드 유형 이름: "계정"
  "record-id": {{json record-id}} // 레코드 아이디
}

composite-salesforce-webhook-task

collateSubrequests 옵션에 대한 정보는 Salesforce 문서에서 확인할 수 있습니다.

아래 예시에서는 "@{createAccount.id}"를 사용하여 첫 번째 하위 요청에서 생성된 레코드의 ID를 참조합니다. 종속 요청에 대한 자세한 내용은 Salesforce 문서에서 알아보십시오.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "request": {
    "collateSubrequests": true,  // 요청들을 모아 처리
    "compositeRequest": {
      "createAccount": {
        "type": "createRecord",  // 레코드 생성
        "createRecord": {
          "recordTypeName": "Account",  // 계정 레코드 타입
          "data": {
            "Name": {{json name}}  // 이름 데이터
          }
        }
      },
      "updateId": {
        "type": "updateRecord",  // 레코드 업데이트
        "updateRecord": {
          "recordTypeName": "Account",  // 계정 레코드 타입
          "data": {
            "Industry": {{json industry}}  // 산업 데이터
          },
          "recordId": "@{createAccount.id}"  // 생성된 계정의 ID
        }
      }
    }
  }
}

SAP

SAP 플러그인을 사용하면 기업용 SAP 환경에 연결하여 비즈니스 API (BAPI)를 호출하여 SAP 비즈니스 오브젝트를 수정할 수 있습니다. SAP 소스를 설정한 후 특정 BAPI로 호출하는 SAP 웹훅을 생성할 수 있습니다.

현재 SAP 플러그인에서 사용할 수 있는 유일한 작업 유형은 sap-run-function-webhook-task-v0입니다. 아래는 이 작업 유형에 대한 작업 본문 예제입니다.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "function-name": "BAPI_SALESORDER_CHANGE",
    // BAPI_SALESORDER_CHANGE 함수 이름
    "inputs": {
        "SALESDOCUMENT": {{json sales-doc-id}},
        // 판매 문서 ID
        "ORDER_HEADER_IN": {
            "PURCH_DATE":  {{json purchase-date}}
            // 구매 날짜
        },
        "ORDER_HEADER_INX": {
            "UPDATEFLAG": "U",
            // 업데이트 플래그
            "PURCH_DATE": "X"
            // 구매 날짜 플래그
        }
    },
    "output": "RETURN",
    // 출력: 반환
    "remote": {
      "context": SAP_CONTEXT_NAME (Optional)
      // 원격: SAP 컨텍스트 이름 (선택 사항)
    }
}

위 작업은 주어진 판매 문서의 구매 날짜를 수정하는 BAPI_SALESORDER_CHANGE라는 BAPI를 호출합니다. 웹훅에 대한 SAP 컨텍스트도 선택적으로 지정할 수 있습니다.

제한

각 웹훅에 대해 실행 방식을 제한하는 세 가지 유형의 제한을 설정할 수 있습니다: 시간 제한, 동시성 제한, 속도 제한.

시간 제한은 웹훅이 실행될 최대 기간을 설정할 수 있습니다. 이를 통해 최종 사용자 애플리케이션을 반응성 있게 유지하고 외부 시스템에 연결하는 데 시간이 오래 걸릴 때 타임아웃 오류를 표시할 수 있습니다. 기본 타임아웃은 값을 제공하지 않으면 20초입니다. 허용되는 최대 타임아웃 값은 90초입니다.

동시성 제한은 한 번에 실행되는 웹훅 실행의 최대 개수를 지정합니다. 이를 통해 너무 많은 동시 요청으로 외부 시스템에 과부하를 주지 않도록 할 수 있습니다.

속도 제한은 지정한 시간 창 내에서 웹훅이 실행될 수 있는 횟수를 제한합니다. 웹훅이 초, 분, 시, 일 단위로 특정 횟수만 실행되도록 보장하려면 이 유형의 제한을 사용할 수 있습니다.

권한

웹훅을 생성, 구성 및 삭제하는 권한은 연관된 출처의 권한에서 확장됩니다.

Data Connection 권한에 대해 자세히 알아보고 웹훅 권한에 대한 자세한 정보를 확인하세요.

기타 옵션

응답 저장

기본적으로 웹훅 응답은 6개월 동안 기록 보기에 저장되고 표시됩니다. 전체 응답은 웹훅을 실행한 사용자와 webhooks:read-privileged-data 권한이 있는 관리자에게만 표시됩니다.

웹훅 기록에 저장해서는 안 되는 민감한 정보를 반환하는 것으로 알려진 웹훅의 경우 이 옵션을 완전히 사용하지 않도록 설정할 수 있습니다.

OAuth 2.0과 웹훅

인증 코드 부여

Palantir 웹훅은 OAuth 2.0 인증 코드 부여 흐름을 사용하여 엔드포인트를 호출하는 데 지원합니다. 이를 위해 OAuth 2.0 서버와의 상호 작용을 정의하는 발신 애플리케이션을 사용해야 합니다. 구성되면 발신 애플리케이션은 REST API 웹훅의 인증으로 사용되며 웹훅을 실행하려는 개별 사용자가 OAuth 서버와 인증하도록 요청합니다.

클라이언트 자격 증명 부여

웹훅을 사용하여 클라이언트 자격 증명을 사용한 OAuth 흐름을 수행할 수 있습니다. 클라이언트 자격 증명 부여 흐름은 일반적으로 대상 시스템에 대한 작업을 수행하는 데 사용할 수 있는 단기 액세스 토큰을 검색하는 데 긴 기간 비밀을 사용합니다. REST API 웹훅은 연속된 여러 API 호출을 지원하며 클라이언트 자격 증명 핸드셰이크를 수행한 후 원하는 요청을 단일 실행으로 수행할 수 있습니다.

다음 안내서에서는 예시 시스템에 대한 클라이언트 자격 증명 부여 흐름을 구성하는 방법을 설명합니다.

진행하려면 다음 정보가 필요합니다:

• OAuth 2.0 서버 도메인 및 토큰 엔드포인트 경로입니다. 토큰 엔드포인트는 리소스 도메인에 대한 요청을 수행하는 유효한 토큰을 검색하는 데 사용됩니다.
  • 많은 경우 OAuth 2.0 서버 도메인과 리소스 도메인이 동일합니다. 예를 들어, 제3자 애플리케이션을 사용하여 인증하는 Foundry API의 경우가 그렇습니다.
• 리소스 도메인 및 OAuth 2.0 서버에서 검색한 베어러 토큰을 포함하는 인증 헤더로 호출하려는 원하는 엔드포인트 경로입니다.
• OAuth 2.0 서버의 클라이언트 ID입니다.
• OAuth 2.0 서버의 클라이언트 비밀입니다.

REST API 출처 생성

먼저 Data Connection 애플리케이션에서 + 새 출처를 선택한 후 출처 유형으로 REST API를 선택합니다. REST API 출처 유형에 대해 자세히 알아보세요.

출처를 구성할 때 OAuth 2.0 서버 도메인과 리소스 도메인을 아래와 같이 추가합니다. 인증 옵션을 선택하지 않고, 웹훅 호출 내에서 직접 OAuth 2.0 핸드셰이크를 수행할 것입니다.

추가 비밀 섹션에서 새 비밀을 추가하고 토큰 엔드포인트에 요청을 할 때 포함될 ClientSecret을 입력하세요. 웹훅 호출을 구성할 때 이 값을 참조하게 됩니다. 여기에 입력하면 ClientSecret은 암호화되어 Foundry의 다른 편집자나 소유자에게도 노출되지 않습니다.

클라이언트 자격 증명 핸드셰이크를 수행하는 웹훅 생성

출처가 생성되면 새 웹훅을 생성할 옵션을 선택합니다.

웹훅은 두 개의 연결된 호출로 구성됩니다:

• 유효한 베어러 토큰을 검색하기 위한 토큰 엔드포인트로의 초기 호출
• 첫 번째 호출에서 구문 분석된 베어러 토큰을 포함하는 리소스 도메인의 원하는 엔드포인트로의 후속 호출

첫 번째 호출을 구성하는 방법의 예시는 아래와 같습니다:

두 번째 호출에서 사용 가능한 구성 옵션을 사용하여 원하는 요청을 작성하세요. 베어러 토큰을 인증 헤더에 삽입하려면 호출 구성의 헤더 섹션으로 이동하여 아래 예시와 같이 헤더를 추가하세요. 이전 호출에서 값을 참조하려면 @를 사용할 수 있습니다. 대부분의 OAuth 2.0 서버는 access_token이라는 JSON 매개변수를 반환합니다. From a call 값을 추가하려는 옵션을 선택한 다음 Extract by key를 선택하고 첫 번째 호출에 대한 응답에서 추출하려는 키 값을 입력하세요.

아래 스크린샷에서 첫 번째 호출에서 베어러 토큰을 선택하는 방법을 보여줍니다:

구성이 완료되면 두 개의 연결된 호출로 구성된 웹훅은 다음 예시와 유사하게 보일 것입니다:

마지막으로, 웹훅의 첫 번째 호출에서 전체 응답을 저장하지 않도록 하는 것이 좋습니다. 응답이 저장되면 웹훅 기록을 볼 수 있는 권한이 있는 다른 사용자가 베어러 토큰을 볼 수 있게 됩니다. 웹훅 구성의 저장 및 보존 페이지에서 토큰 엔드포인트에 대한 요청에 대한 기록 저장을 사용하지 않도록 하는 자동 프롬프트가 표시됩니다. 아래와 같이 보여줍니다: