importStandardData
API v40에서 업데이트됨(2024년 9월 13일)
카테고리
| 데이터 제출 |
설명
| 표준 계정에 데이터를 삽입하거나 바꿉니다. |
호출에 필요한 권한
| 모든 위치로 가져오기
데이터 지우기(대체 모드를 지원하는 API v36 이상) |
요청 시 필수 매개변수
| Credentials, ImportDataOptions, Version, RowData |
includeDescendants
이 메서드의 요청에는 제공된 데이터 행을 수신할 버전을 결정하는 데 사용할 매개변수가 포함되어 있습니다. 계정이 시트에 배치되었는지 여부와 관계없이 모든 표준 계정(GL 계정, 커스텀 계정, 가정 또는 환율)으로 데이터를 가져올 수 있습니다.
importStandardData는
수식 설정 재정의
에데이터 입력을
사용하는 계정으로 가져올 수 없습니다.요청 형식
<?xml version='1.0' encoding='UTF-8'?> <call method="importStandardData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" useMappings="false" /> <version name="Budget 2004" isDefault="false" /> <rowData> <header>Account|Level|Split Label|Product|Region|11/2005|01/2006</header> <rows> <row>70110|Corporate Plan||Bunnyrabbit Toy|Western-US|2037|4032</row> </rows> </rowData> </call>
이 API 호출을 호출할 때마다 나열된 각 유형의 요소가 정확히 하나만 포함되어야 합니다.
- 자격증명
- importDataOptions
- 버전
- rowData
- 헤더
- 행
헤더의 파이프 문자( | ) 수와 데이터가 일치하지 않으면 API v30 이상에서 오류가 발생합니다.
API v36 이상의 경우 importDataOptions 모드 특성이 REPLACE이면 범위 요소도 지정해야 합니다.
예: 바꾸기 모드 요청
|
API v36 이상에서만 사용가능
|
자격증명 요소
| |||
태그명
| 자격증명 | ||
설명
| 모든 API 호출에는 단일Credentials 요소를 사용하여 API를 호출하는 사용자를 식별합니다. 그런 다음 이 사용자로 API 호출이 수행됩니다(시스템의 모든 감사 추적 또는 액션 이력에 이 사용자가 액션을 수행했음이 표시됨). 따라서 사용자에게 액션을 수행하는 데 필요한 권한이 있어야 API 호출이 성공 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
로그인 | 예 | API 메서드를 호출하는 사용자의 로그인명입니다. 이 사용자는 메서드를 호출하는 데 필요한 권한이 있어야 합니다. | sampleuser@company.com |
비밀번호 | 예 | API 메서드를 호출하는 사용자의 비밀번호입니다. | my_password |
로케일 | 아니요 | 수신 숫자 및 날짜를 해석하고 보내는 숫자 및 날짜의 형식을 지정하는 데 사용할 로케일을 지정합니다(적절한 천 단위 구분 기호 사용).기간명 및 날짜 형식) 로케일은 응답의 시스템 메시지에 사용할 언어를 지정하는 데도 사용됩니다. 지정하지 않으면 en_US(미국식 영어)가 사용됩니다. | fr_FR |
instanceCode | 아니요 | 자격증명에 지정된 사용자가 의 두 개 이상의 인스턴스에 액세스할 수 있는지 여부 Adaptive Planning 인 경우 이 특성을 사용하여 사용자가 기본 인스턴스가 아닌 다른 인스턴스에 액세스하려고 함을 지정할 수 있습니다. 지정하지 않으면 사용자의 기본 인스턴스가 사용됩니다. 사용가능한 인스턴스 코드를 확인하려면 exportInstances API를 사용합니다. | MYINSTANCE1 |
요소의 콘텐츠
| |||
(없음) | |||
importDataOptions 요소
| |||||||
태그명
| importDataOptions | ||||||
설명
| 가져오기를 수행할 때 사용할 옵션을 지정합니다. | ||||||
요소의 특성
| |||||||
특성명
| 필수
| 값
| 예:
| ||||
planOrActuals | 예 | '계획" 또는 "실제값"을 사용하여 가져올 데이터 유형을 지정합니다. 이 설정이 에 지정된 버전과 충돌하는 경우버전 태그인버전 태그의 값이 우선하며 이 설정은 무시됩니다. | 계획 | ||||
moveBPtr | 아니요 | 다음과 같은 경우에만 사용됩니다.planOrActuals 특성이 으로 설정됨실제값 조건moveBPtr이 다음으로 설정된 경우true이면 가져오기에서 실제값 버전의 실제값 사용가능 포인터가 가져온 데이터에서 찾은 최신 기간으로 이동합니다. 다음으로 설정된 경우false로 설정하면 가져오기가 버전에 실제값을 표시할 기간에 영향을 주지 않습니다. 다음과 같은 경우 이 특성을 false로 설정해야 합니다.planOrActuals가 으로 설정된 경우계획 | false | ||||
allowParallel | 예 | 다음과 같은 경우에만 사용됩니다.planOrActuals 특성이 으로 설정됨실제값 다음으로 설정된 경우true이면 이 인스턴스에 대해 처리 중인 다른 실제값 또는 트랜잭션 가져오기가 이미 있는 경우에도 가져오기가 진행됩니다. 다음으로 설정된 경우false이면 이 인스턴스에 대해 처리 중인 실제값 또는 트랜잭션 가져오기가 이미 있는 경우 가져오기 시도가 실패합니다. | false | ||||
useMappings | 아니요 | 행 요소 내의 계정, 계획 및 디멘션 값에 대해 가져오기 매핑을 사용할지 여부를 지정합니다. 고려됨기본적으로 true입니다. 조건false인 경우 내부 ID를 사용해야 합니다. 즉, 계정은 코드로, 레벨은 이름으로, 디멘션 값으로 식별됩니다. | false | ||||
includeContext | 아니요 | 메시지에 컨텍스트 블록이 포함될 수 있는지 여부를 지정합니다. 값:false(컨텍스트 표시 안함) 또는true(해당하는 경우 컨텍스트 표시) 지정하지 않으면true로 가정합니다. | false | ||||
displayNameEnabled
표시명을 활성화하는 인스턴스의 API v30 이상에서만 사용할 수 있습니다. | 아니요 | displayNameEnabled=true는 importStandardData가 예상해야 함을 나타냅니다. Account Code , Level Code , Dimension Code 및 Dimension Name Column 인스턴스에 대해 '표시명 사용'이 설정된 경우 페이로드에 포함displayNameEnabled=false는 인스턴스에 대해 '표시명 사용'이 활성화된 경우에도 importStandardData API가 v30 이전 API 계약을 계속 따라야 함을 나타냅니다. importStandardData API가 표시명 속성을 무시합니다. Account Code , Level Code , Dimension Code 및 Dimension Name Column .displayNameEnabled의 기본값은 'false'입니다. | false | ||||
splitsToUnsplit
API v40 이상에서만 사용가능 | 아니요 | splitsToUnsplit=true는 기존 데이터가 있는 분할을 분할되지 않은 위치로 가져올 수 있도록 허용합니다. 이 특성의 기본값은 false입니다. | false | ||||
모드
API v36 이상에서만 사용가능 | 아니요 | 가져오기 모드를 APPEND 또는 REPLACE로 지정합니다.
이 모드 특성은 API v36 이상 버전에서 지원됩니다. mode="REPLACE"를 사용하여 이전 버전의 API를 호출하면 오류가 발생합니다. 지정되지 않은 경우 mode의 기본값은 APPEND입니다. | 추가 | ||||
요소의 콘텐츠
| |||||||
(없음) | |||||||
버전 요소
| |||
태그명
| 버전 | ||
설명
| 요청된 데이터를 수신하는 데 사용해야 하는 버전을 나타냅니다. 각 호출에 대해 버전을 제공해야 합니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
이름 | 아니요 | 데이터를 수신하는 데 사용할 버전의 이름입니다. 단일 API 호출 내에서는 하나의 버전에만 액세스할 수 있습니다. 이름을 입력하지 않으면이 요소에서 isDefault 플래그를 true로 설정해야 합니다.
환산된 통화 버전 및 해당 이름의 목록을 가져오려면 포함 요소에서 CurrencyVersions=true를 지정하여exportVersions를요청합니다. | Budget 2014 |
isDefault | 아니요 | 호출자가 인스턴스의 이름과 관계없이 인스턴스의 현재 기본 버전에 액세스하려는 경우 이 특성을 true로 설정할 수 있으며, 이 경우 태그의 name 특성(있는 경우)이 무시됩니다. 그렇지 않고, 이 값이 false이거나 이 특성이 없는 경우, 이 호출이 성공하려면 제공된 이름을 사용하는 버전이 존재하고 사용자가 액세스할 수 있어야 합니다. | false |
요소의 콘텐츠
| |||
(없음) | |||
범위 요소
| |||
태그명
| 범위
API 버전 36 이상에서만 사용가능 | ||
설명
| 이 가져오기의 범위를 지정합니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
eraseCellNotes | 아니요 | 범위에서 셀 메모를 지울지 여부를 지정합니다. 다음 3가지 열거 값 중 하나여야 합니다.
없음 - 셀 메모를 지우지 않습니다.모두 - 범위 내의 모든 셀 메모를 지웁니다.수정만 - 가져오기를 통해 수정된 범위 내 셀의 셀 메모를 지웁니다. 여기에는 팩트로 가져온 팩트가 있는 이전에 비어 있던 셀과 팩트가 지워진 셀이 포함됩니다.eraseCellNotes를 지정하지 않으면 NONE으로 기본 설정됩니다. | 없음 |
요소의 콘텐츠
| |||
하나 의 시간 요소, 하나의계정 요소 및 하나의 레벨 요소가 모두 필수입니다. | |||
계정 요소
| |||
태그명
| 계정
API 버전 36 이상에서만 사용가능 | ||
설명
| 가져오기 범위의 계정을 지정합니다. 지정된 계정이 있지만 가져오기 데이터에 이 계정에 대한 데이터가 없는 경우, 이 계정의 데이터는 시간 범위 및 나머지 범위 좌표에 대해 제거됩니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 계정 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다.
명시 - 이 모드가 지정되면 가져오기를 위한 계정 범위를 결정하는 계정 하위 요소가 하나 이상 표시됩니다.입력 - 이 모드가 지정되면 계정 범위는 가져오기 데이터에 있는 고유한 계정 세트에 따라 결정됩니다.참고: 표준 가져오기 범위에는 계정 모드="모두"가 허용되지 않습니다. | 명시적 |
요소의 콘텐츠
| |||
mode가 INPUT 이면 <account> 하위 요소가 없어야 합니다.mode가 EXPLICIT 이면 <account> 하위 요소가 하나 이상 있어야 합니다.mode가 EXPLICIT 이고 <account> 하위 요소의 계정 코드가 유효하지 않으면 전체 <accounts> 요소와 더 나아가 <Scope> 요소가 유효하지 않은 것으로 간주됩니다. 유효하지 않은 각 코드에 대한 응답에 오류 메시지가 포함됩니다. | |||
계정 요소
| |||
태그명
| account
API 버전 36 이상에서만 사용가능 | ||
설명
| 가져오기 범위에 포함할 계정 코드를 지정합니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
includeDescendants | 아니요 | 계정이 leaf 계정인 경우 includeDescendants는 영향을 주지 않습니다.
계정이 parent 계정인 경우 이 특성을 true로 지정하면 범위에 이 계정의 leaf descendant가 모두 포함됩니다. 계정이 parent 계정이고 includeDescendants가 false이면 오류입니다. leaf 계정으로만 가져올 수 있습니다. 이는 옵션 특성이며 기본값은 false로 간주됩니다. | true |
선택기 | 아니요 | 계정 요소 콘텐츠 유형을 지정합니다.
선택기의 기본값은 code입니다. | |
요소의 콘텐츠
| |||
가져오기 범위의 일부로 사용되는 계정의 대소문자를 구분하는 계정 코드입니다. 예를 들어, AccountsPayable을 입력합니다. 코드는 비워둘 수 없으며 코드에 해당하는 계정이 있어야 합니다. 계정은 시스템 계정 또는 링크 계정일 수 없습니다. 계정이 계산 계정인 경우 해당 계정에 대한 데이터 입력 재정의가 있어야 합니다. 그렇지 않으면 유효하지 않은 것으로 간주됩니다.
계정 코드가 유효하지 않은 경우, 전체 <accounts> 요소와 확장하여 <range> 요소가 유효하지 않은 것으로 간주됩니다. | |||
레벨 요소
| |||
태그명
| 개 레벨
API 버전 36 이상에서만 사용가능 | ||
설명
| 가져오기 범위의 레벨 코드를 지정합니다. 여기에 레벨 코드가 지정되었지만 가져오기 데이터에 이 레벨에 대한 데이터가 없으면 시간 범위 및 나머지 범위 좌표에 대해 이 레벨의 데이터가 제거됩니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 레벨 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다.
EXPLICIT - 이 모드가 지정되면 가져오기의 레벨 범위를 결정하는 하나 이상의 <level> 하위 요소가 표시됩니다.입력 - 이 모드가 지정되면 레벨 범위는 가져오기 데이터에 있는 고유한 레벨 세트에 따라 결정됩니다.모두 - 이 모드를 지정하면 레벨 범위가 모두 가져오기 가능한 레벨이 됩니다. | 명시적 |
요소의 콘텐츠
| |||
mode가 INPUT 또는 ALL이면 <level> 하위 요소가 없어야 합니다.
mode가 EXPLICIT이면 하나 이상의 <level> 하위 요소가 있어야 합니다. mode가 EXPLICIT이고 <level> 하위 요소의 레벨 코드가 유효하지 않은 경우 전체 <levels> 요소와 더 나아가 <Scope> 요소가 유효하지 않은 것으로 간주됩니다. 유효하지 않은 각 코드에 대한 응답에 오류 메시지가 포함됩니다. | |||
레벨 요소
| |||
태그명
| level
API 버전 36 이상에서만 사용가능 | ||
설명
| 가져오기 범위에 포함할 레벨 코드를 지정합니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
includeDescendants | 아니요 | 레벨이 parent 레벨인 경우 이 특성을 true로 지정하면 범위의 자체(전용 노드)를 포함하여 이 레벨의 모든 leaf descendant가 포함됩니다.
이는 옵션 특성입니다. 특성이 제공되지 않은 경우 기본값은 false입니다. 특성이 제공되지 않거나 false로 제공되고 지정된 레벨이 parent 레벨인 경우, 이는 가져오기에서 해당 레벨의 Only(예: Engineering Only) 노드를 범위로 간주함을 의미합니다. 레벨의 child 레벨은 다른 레벨 요소에서 명시적으로 지정하지 않는 한 범위에 포함되지 않습니다. | true |
요소의 콘텐츠
| |||
레벨의 대소문자를 구분하는 코드를 지정합니다. 예를 들어, <level>개발/레벨>입니다. 레벨 코드에 문제가 있는 경우(예: 코드를 찾을 수 없는 레벨), 전체 <levels> 및 확장하여 <range>가 유효하지 않은 것으로 간주됩니다. 유효하지 않은 각 코드에 대한 응답에 오류 메시지가 포함됩니다. | |||
시간 요소
| |||
태그명
| time
API 버전 36 이상에서만 사용가능 | ||
설명
| 가져오기를 위한 시간 범위를 나타내는 하나 이상의 시간 범위를 지정합니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 시간 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다. 입력 - 이 모드가 지정되면 시간 범위는 의 시간 코드에 의해 결정됩니다. <header> 요소 헤더에 2개월이 포함된 경우 가져오기 범위는 이 2개월입니다.EXPLICIT - 이 모드가 지정되면 가져오기의 시간 범위를 결정하는 하나 이상의 timeRange 하위 요소가 표시됩니다.버전 - 이 모드가 지정되면 시간 범위는 초기 산정기간을 포함하여 버전의 시작 및 종료 시점이 됩니다.모드가 INPUT 또는 VERSION이면 timeRange 하위 요소가 허용되지 않습니다. timeRange 하위 요소가 있으면 오류로 처리됩니다. | INPUT |
요소의 콘텐츠
| |||
하나 이상의 timeRange 요소 - mode가 INPUT 또는 VERSION이 아닌 경우 | |||
timeRange 요소
| |||
태그명
| timeRange
API 버전 36 이상에서만 사용가능 | ||
설명
| 시간 범위에 대해 단일 시간 범위를 지정합니다.
importDataOptions 요소의 모드 특성이 REPLACE인 경우에만 허용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
시작 | 예 | 가져오기 시간 범위의 시작 기간입니다. | 07/2021 |
종료 | 예 | 가져오기 시간 범위의 종료 기간입니다. | 08/2021 |
요소의 콘텐츠
| |||
하나 이상의 timeRange 요소 - mode가 INPUT 또는 VERSION이 아닌 경우 | |||
rowData 요소
| |||
태그명
| rowData | ||
설명
| 가져오는 데이터 행의 컨테이너입니다. | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
정확히 1개헤더 요소 및 정확히 하나행 요소 | |||
헤더 요소
| |||
태그명
| 헤더 | ||
설명
| 해당하는 데이터의 열 이름과 순서를 지정합니다.행 요소 | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
세로 막대로 구분된 열 이름이 있는 텍스트 줄입니다. 이러한 열 이름은 시트의 디멘션 또는 필드 이름 또는 데이터를 포함할 수 있는 기간 코드와 일치해야 합니다. 이 이름은 데이터를 가져올 대상 시트의 가져오기 템플릿에 있는 열 이름과 동일하며, 각 열 헤더가 세로 막대 또는 파이프 기호로 구분되어 있습니다.
표시명을 활성화하는 인스턴스의 경우 헤더가 다음을 지원하지 않습니다. "<dimension>" 조합 "<dimension> Name" 또는 "<dimension> Code" Adaptive Planning 지원 로케일의 경우 API v30 이상 | |||
행 요소
| |||
태그명
| 행 | ||
설명
| 하나 이상의 컨테이너행 요소 | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
하나 이상행 요소 | |||
행 요소
| |||
태그명
| 행 | ||
설명
| 가져오는 단일 행의 데이터입니다. | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
가져오는 단일 행의 필드에 대한 데이터이며, 각 필드의 값은 세로 막대 또는 파이프 기호로 구분됩니다. 데이터 필드는 헤더 요소의 라인과 순서가 동일해야 합니다. 값의 숫자가 천 단위 구분 기호를 사용하는 경우, 해당 숫자는 요청의 자격증명에 지정된 로케일에서 사용되는 쉼표 구분 기호로 간주됩니다. | |||
응답 형식
다음은 표준 계정 데이터 가져오기 성공 및 실패에 대한 응답의 예입니다.
성공 예
<?xml version='1.0' encoding='UTF-8'?> <response success="true"></response>
실패(컨텍스트 있음)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-empty-account"> <context> <col header="Account" value="" /> <col header="Level" value="Corporate Plan" /> <col header="Split Label" value="" /> <col header="Product" value="Bunnyrabbit Toy" /> <col header="Region" value="Western-US" /> <col header="11/2005" value="2037" /> <col header="01/2006" value="4032" /> </context> Account cannot be empty on row 1. </message> </messages> </response>
실패(컨텍스트 없음)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-empty-account">Account cannot be empty on row 1.</message> </messages> </response>
응답 요소
| |||
태그명
| 응답 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
성공 | 예 | 둘 중 하나true 또는false - API 호출의 성공 여부를 나타냅니다. 성공한 호출의 경우에도 응답에 경고 메시지가 포함될 수 있습니다. | true |
요소의 콘텐츠
| |||
단일 옵션메시지 요소 | |||
메시지 요소
| |||
태그명
| 메시지 | ||
설명
| 하나 이상의 컨테이너메시지 요소 | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
하나 이상메시지 요소 | |||
메시지 요소
| |||
태그명
| 메시지 | ||
설명
| 시스템에서 호출자에게 다시 전송되는 메시지를 나타냅니다. 이 메시지는 요청이 성공하지 못한 경우의 오류 메시지, 요청이 성공한 경우의 경고 메시지, 성공한 경우의 확인 메시지에 사용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
키 | 아니요 | 지정된 경우 키는 특정 메시지 또는 메시지 유형을 식별하는 방법이며, 클라이언트 프로그램에서 자동화된 오류 기록 및 복구를 위해 유용합니다. 메시지의 언어가 변경되더라도 다른 요청 로케일에서는 키는 변경되지 않습니다. 또한 향후에는 문구 조정 또는 용어 변경으로 인해 키가 변경되지 않을 것입니다. | invalid-attributevalueid |
요소의 콘텐츠
| |||
| |||
컨텍스트 요소
| |||
태그명
| context | ||
설명
| 하나 이상의 col 요소에 대한 컨테이너입니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
없음 | |||
요소의 콘텐츠
| |||
하나 이상의 col 요소 | |||
열 요소
| |||
태그명
| 열 | ||
설명
| 메시지의 컨텍스트를 나타냅니다. 메시지를 생성하는 행을 식별할 수 있도록 헤더/값 쌍을 제공합니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
헤더 | 예 | 열의 헤더입니다. | "Account" |
값 | 예 | 열의 값입니다. | "GL-29482-38233" |
요소의 콘텐츠
| |||
(없음) | |||