주 컨텐츠로 이동
Adaptive Planning
최종 업데이트: 2024-09-20
importConfigurableModelData

importConfigurableModelData

API v40에서 업데이트되었습니다(2024년 9월 21일).
카테고리
데이터 제출
설명
모델링 시트에서 데이터를 삽입, 바꾸기 또는 업데이트합니다.
호출에 필요한 권한
가져오기
요청 시 필수 매개변수
Credentials, ImportDataOptions, Version, Sheet, RowData
이 메서드의 요청에는 제공된 데이터 행을 수신할 시트와 버전을 결정하는 데 사용할 매개변수가 포함되어 있습니다.
이 방법은 다음을 수행할 수 있습니다.
  • 시트에 신규 행을 추가합니다.
  • 현재 모델링 시트에 있는 모든 행을 가져오기로 바꿉니다.
  • 가져온 레벨에서만 시트의 데이터 모두 바꾸기
  • 가져오기의 행을 가져오기 키로 매칭하여 기존 행을 업데이트합니다.
  • 가져오기의 행을 가져오기 키로 매칭하여 기존 행을 업데이트하고 새 행을 추가합니다.
이 API 호출을 호출할 때마다 나열된 각 유형의 요소가 정확히 하나만 포함되어야 합니다.
  • 자격증명
  • importDataOptions
  • 버전
    • 시트
    • rowData
헤더의 파이프 문자( | ) 수와 데이터가 일치하지 않으면 API v30 이상에서 오류가 발생합니다.
API v37부터 모델링 시트로 가져올 수 있는 신규 행의 최대 개수가 제한됩니다. 이 한도에 도달하면 지원팀에 문의하십시오.

요청 형식

<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" 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" replaceExisting="2"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Level|Region|Title|JobCode|Benefits|per|Last Name|First Name|ID|Start|End|Hr/Week|Pay Rate|Pay Rate Display Column</header> <rows> <row>Corporate Plan|Any|CEO|E1|Yes|Yr|Topdog|Andy|1000|12/20/2013|12/30/2014|80|500,000.12|888,888</row> </rows> </rowData> </call>

importKey를 사용하여 기존 행 업데이트 요청 형식

<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" replaceExisting="3" importKey="Region" allowParallel="false" moveBPtr="false" useMappings="false"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Plan|Region|Benefits|per</header> <rows> <row>Europe Sales|W-US|Yes|Hr</row> </rows> </rowData> </call>
자격증명 요소
태그명
자격증명
설명
모든 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
아니요
가져오는 데이터에 각 행의 시간 프레임 번호 세트가 있는 경우에만 사용됩니다. 조건moveBPtr이 다음으로 설정된 경우true이면 가져오기에서 실제값 버전의 실제값 사용가능 포인터가 가져온 데이터에서 찾은 최신 기간으로 이동합니다. 다음으로 설정된 경우false로 설정하면 가져오기가 버전에 실제값을 표시할 기간에 영향을 주지 않습니다. planOrActuals가 Plan으로 설정된 경우 이 특성을 false로 설정해야 합니다.
false
allowParallel
다음으로 설정된 경우true이면 이 인스턴스에 대해 처리 중인 다른 실제값 또는 트랜잭션 가져오기가 이미 있는 경우에도 가져오기가 진행됩니다. 다음으로 설정된 경우false이면 이 인스턴스에 대해 처리 중인 실제값 또는 트랜잭션 가져오기가 이미 있는 경우 가져오기 시도가 실패합니다.
false
useMappings
아니요
행 요소 내의 계정, 계획 및 디멘션 값에 대해 가져오기 매핑을 사용할지 여부를 지정합니다. 고려됨기본적으로 true입니다. 조건false인 경우 내부 ID를 사용해야 합니다. 즉, 계정은 코드로, 레벨은 이름으로, 디멘션 값으로 식별됩니다.
false
replaceExisting
아니요
모든 레벨의 기존 행을 가져오는 새 행으로 바꾸려면 '1' 또는 'true'로 설정합니다. (즉, 모든 레벨에서 이전에 존재하는 모든 행을 지웁니다.)
모든 위치로 가져오기
권한이 있는 사용자만 이 옵션을 사용할 수 있습니다.
새 행이 중복된 경우에도 가져온 행을 기존 행에 추가하려면 '0' 또는 'false'로 설정합니다.
모델링 시트의 기존 행을 가져올 신규 행으로 바꾸려면 '2'로 설정합니다. 단, 레벨 및 보안 설정된 디멘션이 일치하는 행에만 해당합니다. 행이 업로드에 의해 대체되는 행의 분할이 아닌 한, 업로드된 스프레드시트에 분할되지 않은 행이 없는 레벨 및 보안 설정된 디멘션 조합의 행은 기존 행이 제거되지 않습니다.
createExisting은 사용된 디멘션을 검사하고, 데이터가 동일한 레벨, 계정, 기간 및 버전에 존재하는지 여부를 검사합니다. 행 키가 있으면 행 키 열과도 일치 여부를 확인합니다.
시스템의 동일한 위치에 데이터가 있는 경우 가져오기가 해당 데이터를 바꿉니다. 데이터 바꾸기는 행별로 수행됩니다. 가져오기 작업이 모든 항목을 한 번에 바꾸는 것은 아닙니다. 일치하지 않는 가져오기 행이 시트에 추가됩니다.
예를 들어, 두 가지 가져오기를 수행합니다. 첫 번째 가져오기 파일은 두 번째 가져오기 파일에 포함되지 않은 데이터를 로드합니다. 해당 기존 데이터는 두 번째 가져오기 후에도 남아 있습니다.
특정 열의 데이터를 모두 삭제하려면 해당 열을 포함하되 열 값은 비워 둡니다. 언급되지 않은 열의 열 값은 변경되지 않은 상태로 유지됩니다.
가져오는 신규 행을 반영하도록 모델링 시트의 기존 행을 업데이트하려면 '3'으로 설정합니다. 기존 행과 일치하지 않는 행이 있으면 경고가 반환됩니다. 이 모드에는 importKey가 필요합니다.
분할 허용이
선택된 시트는 업데이트를 지원하지 않습니다.
가져오는 신규 행을 반영하도록 모델링 시트의 기존 행을 업데이트하고, 기존 행과 일치하지 않는 행에 대해 신규 행을 삽입하려면 '4'로 설정합니다. 이 모드에는 importKey가 필요합니다. 필수 열은 가져오기 키, 레벨 및 모든 텍스트 선택기에 해당되며, 신규 행을 추가하지 않는 경우에도 마찬가지입니다.
분할 허용이
선택된 시트는 업데이트를 지원하지 않습니다.
현재는 레벨별 바꾸기 전용 기능에 대한 입력 레벨만 지원하는 범위를 기준으로 기존 행을 바꾸려면 5로 설정합니다. 새 범위 요소를 사용하여 범위가 제공됩니다. 지정된 범위와 일치하는 행만 가져오기의 페이로드로 대체됩니다. 범위와 일치하지 않는 행은 영향을 받지 않습니다.
기본값은 true입니다.
true
importKey
아니요
모델링 시트 행을 업데이트할 때 가져오기 키로 사용할 모델링 시트 열 이름입니다.
Adaptive Planning
에서는 가져오기 키 열을 사용하여 가져오기의 각 행을 모델링 시트의 행과 매칭합니다. 모든 행의 가져오기 키 값은 고유해야 합니다.
이 특성은 바꾸기기존 값이 '3' 또는 '4'인 경우에만 사용할 수 있습니다.
가져오기 키 열은 다음 중 하나일 수 있습니다.
  • 레벨 열
  • 디멘션 열
Level
includeContext
아니요
메시지에 컨텍스트 블록이 포함될 수 있는지 여부를 지정합니다. 값:false(컨텍스트 표시 안함) 또는true(해당하는 경우 컨텍스트 표시) 지정하지 않으면true로 가정합니다.
false
displayNameEnabled
표시명을 활성화하는 인스턴스의 API v31 이상에서만 사용할 수 있습니다.
아니요
displayNameEnabled=true는 인스턴스에 대해 '표시명 사용' 설정이 켜져 있을 때 API가 페이로드에 계정 코드, 레벨 코드, 디멘션 코드 및 디멘션명 열을 포함해야 함을 나타냅니다.
displayNameEnabled=false는 인스턴스에 대해 '표시명 사용' 설정이 ON인 경우에도 API가 v30 이전 API 계약을 따라야 함을 나타냅니다.
displayNameEnabled의 기본값은 'false'입니다.
false
applyValidationRules
API v38 이상에서만 사용할 수 있습니다.
아니요
applyValidationRules=true는 API 버전이 v38 이상이면 가져온 모든 데이터에 대해 API가 모델링 시트 규칙 검증을 수행함을 나타냅니다.
applyValidationRules=false는 API가 가져온 모든 데이터에 대한 모델링 시트 규칙 검증을 무시함을 나타냅니다.
applyValidationRules의 기본값은 'true'입니다.
false
요소의 콘텐츠
(없음)
버전 요소
태그명
버전
설명
요청된 데이터를 수신하는 데 사용해야 하는 버전을 나타냅니다. 각 호출에 대해 버전을 제공해야 합니다.
요소의 특성
특성명
필수
예:
이름
아니요
데이터를 수신하는 데 사용할 버전의 이름입니다. 단일 API 호출 내에서는 하나의 버전에만 액세스할 수 있습니다. 이름을 입력하지 않으면isDefault 플래그를 으로 설정해야 합니다.이 요소는 true입니다.
Budget 2014
isDefault
아니요
호출자가 인스턴스의 이름과 관계없이 인스턴스의 현재 기본 버전에 액세스하려는 경우 이 특성을 true로 설정할 수 있으며, 이 경우 태그의 name 특성(있는 경우)이 무시됩니다. 그렇지 않고, 이 값이 false이거나 이 특성이 없는 경우, 이 호출이 성공하려면 제공된 이름을 사용하는 버전이 존재하고 사용자가 액세스할 수 있어야 합니다.
false
요소의 콘텐츠
(없음)
시트 요소
태그명
시트
설명
가져온 데이터를 수신해야 하는 시트를 나타냅니다. 각 API 호출은 하나의 시트 데이터만 대상으로 지정할 수 있습니다.
요소의 특성
특성명
필수
예:
이름
데이터를 가져올 시트의 이름입니다.
직원
isUserAssigned
아니요
시트가 사용자 지정 시트임을 나타냅니다. 지정하지 않으면 레벨 지정 시트임을 나타내는 false가 기본값으로 설정됩니다.
false
요소의 콘텐츠
(없음)
범위 요소
태그명
범위(API v40에서 사용가능)
설명
이 가져오기의 범위를 지정합니다. 예를 들어 다음과 같습니다.
<scope> <levels> mode="INPUT"/> </scope>
importDataOptions 요소의 createExisting 특성이 5인 경우에만 허용됩니다.
rowData 요소
태그명
rowData
설명
가져오는 데이터 행의 컨테이너입니다.
요소의 특성
(없음)
요소의 콘텐츠
정확히 1개헤더 요소 및 정확히 하나행 요소
헤더 요소
태그명
헤더
설명
해당하는 데이터의 열 이름과 순서를 지정합니다.행 요소
요소의 특성
(없음)
요소의 콘텐츠
세로 막대로 구분된 열 이름이 있는 텍스트 줄입니다. 이러한 열 이름은 시트의 디멘션 또는 필드 이름 또는 데이터를 포함할 수 있는 기간의 코드와 일치해야 합니다. 이 이름은 데이터를 가져올 대상 시트의 가져오기 템플릿에 있는 열 이름과 동일하며, 각 열 헤더가 세로 막대 또는 파이프 기호 | .
표시명을 활성화하는 인스턴스의 경우 헤더가 다음을 지원하지 않습니다.
"<dimension>"
조합
"<dimension> Name"
또는
"<dimension> Code"
Adaptive Planning 지원 로케일의 경우 API v30 이상
행 요소
태그명
설명
하나 이상의 컨테이너행 요소
요소의 특성
(없음)
요소의 콘텐츠
하나 이상행 요소
행 요소
태그명
설명
가져오는 단일 행의 데이터입니다.
요소의 특성
(없음)
요소의 콘텐츠
가져오는 단일 행의 필드에 대한 데이터이며, 각 필드의 값은 세로 막대 또는 파이프 기호로 구분됩니다. 데이터 필드는 헤더 요소의 라인과 순서가 동일해야 합니다. 값의 숫자가 천 단위 구분 기호를 사용하는 경우, 해당 숫자는 요청의 자격증명에 지정된 로케일에서 사용되는 쉼표 구분 기호로 간주됩니다.

응답 형식

다음은 데이터 가져오기 성공 및 실패에 대한 응답의 예입니다.

성공 예

<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="modeled-import-success">Personnel import successful. Rows imported: 1</message> <message key="modeled-import-replace">All existing rows were replaced.</message> </messages> </response>

실패(컨텍스트 있음)

<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate"> <context> <col header="Plan" value="Development1" /> <col header="Region" value="C-US" /> <col header="Title" value="CEO" /> <col header="JobCode" value="E1" /> <col header="Benefits" value="Yes" /> <col header="per" value="Yr" /> <col header="Last Name" value="Topdog" /> <col header="First Name" value="Andy" /> <col header="ID" value="1000" /> <col header="Start" value="12/20/2013" /> <col header="End" value="12/30/2014" /> <col header="Hr/Week" value="80.0" /> <col header="Pay Rate" value="500000.12" /> <col header="Pay Rate Display Column" value="888,888" /> </context> Invalid Level Choice: Development1 on row 1 column A </message> </messages> </response>

실패(컨텍스트 없음)

<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate">Invalid Level Choice: Development1 on row 1 column A</message> </messages> </response>
응답 요소
태그명
응답
요소의 특성
특성명
필수
예:
성공
둘 중 하나true 또는false - API 호출의 성공 여부를 나타냅니다. 성공한 호출의 경우에도 응답에 경고 메시지가 포함될 수 있습니다.
true
요소의 콘텐츠
단일 옵션메시지 요소
메시지 요소
태그명
메시지
설명
하나 이상의 컨테이너메시지 요소
요소의 특성
(없음)
요소의 콘텐츠
하나 이상메시지 요소
메시지 요소
태그명
메시지
설명
시스템에서 호출자에게 다시 전송되는 메시지를 나타냅니다. 이 메시지는 요청이 성공하지 못한 경우의 오류 메시지, 요청이 성공한 경우의 경고 메시지, 성공한 경우의 확인 메시지에 사용됩니다.
요소의 특성
특성명
필수
예:
아니요
지정된 경우 키는 특정 메시지 또는 메시지 유형을 식별하는 방법이며, 클라이언트 프로그램에서 자동화된 오류 기록 및 복구를 위해 유용합니다. 메시지의 언어가 변경되더라도 다른 요청 로케일에서는 키는 변경되지 않습니다. 또한 향후에는 문구 조정 또는 용어 변경으로 인해 키가 변경되지 않을 것입니다.
invalid-attributevalueid
요소의 콘텐츠
  1. 메시지 텍스트입니다. 이 텍스트는 요청에 지정된 로케일의 언어로 표시됩니다(로케일이 지원된다고 가정). 이 텍스트에는 처리된 행 수, 오류가 발생한 특정 열 또는 값과 같은 가변 정보가 포함될 수도 있습니다.
  2. 옵션 컨텍스트 요소입니다.
컨텍스트 요소
태그명
context
설명
하나 이상의 col 요소에 대한 컨테이너입니다.
요소의 특성
특성명
필수
예:
없음
요소의 콘텐츠
하나 이상의 col 요소
열 요소
태그명
설명
메시지의 컨텍스트를 나타냅니다. 메시지를 생성하는 행을 식별할 수 있도록 헤더/값 쌍을 제공합니다.
요소의 특성
특성명
필수
예:
헤더
열의 헤더입니다.
"Account"
열의 값입니다.
"GL-29482-38233"
요소의 콘텐츠
(없음)