Microsoft Dataverse node를 사용하면 Microsoft Dataverse에서 작업을 자동화하고 다른 애플리케이션과 통합할 수 있습니다. Dataverse Web API를 사용하여 표준 테이블과 사용자 지정 테이블의 행을 생성, 읽기, 업데이트, 삭제할 수 있습니다.

Operations#

• Row
  • Create: 새 행을 추가합니다.
  • Create or Update: 행 ID 또는 대체 키를 사용하여 행을 생성하거나 기존 행을 업데이트합니다.
  • Delete: 행을 삭제합니다.
  • Get: ID로 행을 가져옵니다.
  • Get Many: 필터링과 정렬을 선택적으로 적용하여 여러 행을 가져옵니다.
  • Update: 기존 행을 업데이트합니다. 이 작업은 존재하지 않는 행을 생성하지 않습니다.

테이블과 행 선택#

Resource를 Row로 설정한 다음 Operation을 선택합니다.

Table Name or ID에서 From List를 선택하면 환경의 테이블을 검색할 수 있습니다. 테이블을 직접 입력하려면 By ID를 선택하고 accounts 또는 contacts와 같은 Web API 엔터티 집합 이름을 입력합니다. 이 값은 테이블의 표시 이름, 단수 논리적 이름, GUID가 아닙니다.

Get, Update, Delete의 경우 Row ID에서 From List로 행을 선택하거나 By ID로 GUID를 입력합니다. 예를 들어 00000000-0000-0000-0000-000000000001은 필요한 형식을 보여 주는 예시입니다. 사용자 환경에 있는 행의 ID로 바꿔서 입력하세요.

대체 키 주소 지정은 Create or Update에서만 지원됩니다.

행 생성 및 업데이트#

Create, Update, Create or Update의 경우 Input Mode를 선택합니다.

필드를 하나 이상 제공해야 합니다. 노드는 비어 있는 행 항목을 거부합니다. 필드 선택기에는 선택한 작업에서 쓰기 가능한 칼럼이 표시됩니다. Create or Update의 경우 행 생성과 업데이트를 모두 지원하는 칼럼이 표시됩니다.

Field Value 입력은 문자열 필드입니다. 노드는 리터럴 텍스트를 숫자나 불리언으로 자동 변환하지 않습니다. 이러한 유형을 유지하거나 null을 보내야 하면 JSON을 사용하세요.

계정 생성#

계정을 생성하려면 Create를 선택하고 Table Name or ID를 accounts로 설정한 다음 JSON 입력을 사용합니다. **Row Item (JSON)**에 다음 객체를 입력합니다.

{
	"name": "Contoso",
	"accountnumber": "ACC-001",
	"numberofemployees": 25,
	"creditonhold": false
}

Update의 경우 기존 계정의 Row ID를 선택하고 변경하려는 필드만 보냅니다. 예를 들어 {"telephone1": "555-0100"}은 다른 필드를 바꾸지 않고 전화번호만 업데이트합니다.

조회 칼럼 설정#

조회(lookup) 칼럼은 다른 테이블의 행을 참조합니다. 관계 메타데이터에 접근할 수 있으면 노드가 조회 값을 Dataverse에서 요구하는 탐색 속성 바인딩으로 변환합니다.

꺾쇠괄호로 표시한 자리 표시자는 사용자 환경에 있는 행의 GUID로 바꿉니다. 이러한 참조에서 맨 앞의 슬래시는 생략할 수 있습니다.

예를 들어 계정의 기본 연락처와 소유자를 설정하려면 **Row Item (JSON)**에 다음 필드를 포함합니다.

{
	"primarycontactid": "/contacts(<contact-id>)",
	"ownerid": "/systemusers(<user-id>)"
}

{"primarycontactid@odata.bind": "/contacts(<contact-id>)"}와 같이 명시적 바인딩을 제공할 수도 있습니다. 노드는 명시적 바인딩을 변경하지 않고 그대로 전달합니다. 테이블 메타데이터에 있는 탐색 속성 이름을 대소문자까지 정확히 사용하세요. 이 이름은 칼럼 논리적 이름과 다를 수 있습니다.

대상 테이블이 하나인 조회를 지우려면 {"primarycontactid": null}처럼 null을 보냅니다. 여러 테이블을 대상으로 하는 조회는 Dataverse가 해당 관계를 지우도록 허용하는 경우, 대신 해당 탐색 속성을 지정하여 지웁니다.

행 생성 또는 업데이트#

Create or Update를 선택하면 다음 Identifier Type 값 중 하나로 행을 지정할 수 있습니다.

• Row ID (GUID): Row ID를 선택하거나 입력합니다. 행이 존재하지 않으면 Dataverse가 해당 GUID로 행을 생성합니다.
• Alternate Key: Alternate Key Predicate를 입력합니다(예: accountnumber='ACC-001'). 사용하기 전에 Dataverse의 테이블에 대체 키를 구성해야 합니다.

테이블 이름이나 바깥 괄호 없이 조건식(predicate)만 입력합니다. 문자열 키는 값 주위의 작은따옴표를 유지합니다. 노드는 조건식에 포함된 URL 구분자, 경로 구분자, 제어 문자를 거부합니다.

Options에서 Behavior를 사용하여 쓰기 동작을 제어합니다.

예를 들어 accounts 테이블을 선택하고 Alternate Key를 고른 다음 accountnumber='ACC-001'을 입력합니다. **Row Item (JSON)**에 {"name": "Contoso"}를 보내면 해당 계정 번호의 계정을 생성하거나 업데이트합니다.

행 쿼리#

Get 작업은 Options 아래의 Select Column Names or IDs와 Expand Query를 지원합니다. Get Many는 이 옵션들과 함께 추가 필터, 정렬, 결과 제한을 지원합니다.

OData로 여러 행 가져오기#

Get Many를 선택하고 다음 매개변수를 구성합니다.

예를 들어 이름이 Contoso로 시작하는 활성 계정을 최대 100개 가져오려면 다음과 같이 합니다.

1. Table Name or ID를 accounts로 설정합니다.
2. Return All을 끈 상태로 두고 Limit을 100으로 설정합니다.
3. Options에서 Select Column Names or IDs의 name과 accountnumber를 선택합니다.
4. Filter Rows를 statecode eq 0 and startswith(name,'Contoso')로 설정합니다.
5. Sort Column Name or ID를 name으로, Sort Direction을 Ascending으로 설정합니다.

읽기용 칼럼 선택기는 _primarycontactid_value와 같은 조회 속성 이름을 자동으로 사용합니다. 원시 필터나 정렬 표현식을 작성할 때 조회 GUID에는 이 속성 형식을 사용하세요. 예를 들어 _primarycontactid_value eq <contact-id>로 필터링하며, <contact-id>는 따옴표 없는 GUID로 바꿉니다. Expand Query에는 탐색 속성 이름을 사용합니다.

페이지네이션과 결과 제한#

OData 쿼리의 경우 노드는 Limit에 도달하거나 사용 가능한 모든 결과를 가져올 때까지 @odata.nextLink를 따라갑니다.

Limit이 5,000 이하이면 노드는 이 값을 $top으로도 전송합니다. 더 큰 제한값에서는 Dataverse가 여러 페이지를 반환할 수 있도록 $top을 설정하지 않습니다. 명시적인 **Row Count ($Top)**가 우선하며, Return All이 켜져 있어도 결과를 제한할 수 있습니다.

5,000개를 초과하는 행을 가져오려면 **Row Count ($Top)**를 설정하지 않은 상태로 두고, Return All을 활성화하거나 Limit을 5,000보다 크게 설정합니다. 이러한 페이징 규칙은 FetchXML이 아니라 OData 쿼리에 적용됩니다.

FetchXML 사용#

Options > FetchXML Query를 설정하면 FetchXML 쿼리를 실행합니다. 이 설정은 OData의 select, filter, sort, expand, top 옵션을 대체합니다. Return All은 끈 상태로 두고, Limit을 설정하여 반환되는 행 수를 제한합니다.

예를 들어 accounts 테이블을 선택하고 다음 쿼리를 입력하면 활성 계정을 최대 50개 가져옵니다.

<fetch top="50">
	<entity name="account">
		<attribute name="name" />
		<attribute name="accountnumber" />
		<filter>
			<condition attribute="statecode" operator="eq" value="0" />
		</filter>
	</entity>
</fetch>

Table Name or ID는 엔터티 집합 이름 accounts를 사용하지만, FetchXML은 테이블의 논리적 이름인 account를 사용합니다.

탄력적 테이블 사용#

Get, Get Many, Delete에서 탄력적 테이블(elastic table)의 파티션을 대상으로 지정해야 하면 Options > Partition ID를 설정합니다.

Create, Update, Create or Update는 Partition ID 옵션을 제공하지 않습니다. Create에서 파티션된 행을 생성할 때는 행 JSON에 partitionid를 포함합니다.

파티션된 행을 업데이트하거나 upsert하려면 Identifier Type을 Alternate Key로 설정한 Create or Update를 사용합니다. Alternate Key Predicate에 테이블의 기본 키와 partitionid를 포함합니다.

<primary-key-column>=<row-id>,partitionid='<partition-id>'

자리 표시자를 테이블의 기본 키 칼럼 논리적 이름, 행 GUID, 파티션 ID로 바꿉니다. 행이 이미 존재해야 한다면 Behavior를 Update Only로 설정합니다. 테이블별 동작과 제한 사항은 Microsoft의 탄력적 테이블 문서를 참조하세요.

출력과 메타데이터#

• Create, Update, Create or Update는 쓰기 후 행을 요청하고 Dataverse의 응답을 반환합니다.
• Get은 단일 행을 반환합니다.
• Get Many는 value 필드 안의 컬렉션이 아니라 각 행을 별도의 n8n 항목으로 반환합니다.
• Delete는 삭제에 성공하면 {"success": true, "id": "<row-id>"}를 반환합니다.

Delete를 제외한 모든 작업에서 Options > Return Full Metadata를 사용할 수 있으며, 기본값은 꺼짐입니다. 이 옵션을 켜면 Dataverse가 제공하는 서식 지정 값을 포함한 OData 주석을 요청합니다. 노드는 칼럼 이름을 바꾸거나 주석을 단순화하지 않습니다.

일반적인 문제#

테이블 또는 칼럼 옵션이 로드되지 않음#

선택기에 표시되는 HTTP 상태와 Dataverse 오류를 확인합니다. 환경 URL과 테이블 메타데이터 접근 권한을 포함한 자격 증명 접근 권한을 확인합니다. Microsoft Dataverse 자격 증명 문제 해결을 참조하세요.

테이블의 엔터티 집합 이름을 알고 있다면 Table Name or ID > By ID를 사용하여 직접 입력할 수 있습니다. 이 방법은 Dataverse 권한을 우회하지 않습니다.

조회 값이 거부됨#

표시 이름을 조회 값으로 사용하지 마세요. 대상 테이블이 하나인 조회에는 GUID를 사용하고, 그렇지 않으면 엔터티 집합 이름과 행 ID가 포함된 참조를 사용합니다. Customer와 Owner 칼럼에는 대상 테이블을 명시해야 합니다. 예시는 조회 칼럼 설정을 참조하세요.

쿼리가 예상보다 적은 행을 반환함#

Limit을 확인하고, 페이징이 필요하면 **Row Count ($Top)**를 제거하며, 쿼리가 FetchXML을 사용하는지 확인합니다. 페이지네이션과 결과 제한 및 FetchXML 사용을 참조하세요.

관련 리소스#

• Microsoft Dataverse 자격 증명
• Dataverse Web API 문서
• Web API를 사용하여 데이터 쿼리
• Web API에서 대체 키 사용