importCubeData
카테고리
| 데이터 제출 |
설명
| 큐브 시트에 데이터를 삽입하거나 바꿉니다. 이 방법을 사용하면 큐브의 위치로 값이 0인 항목을 가져와 큐브 시트에서 데이터를 삭제할 수도 있습니다. 0을 큐브 시트로 가져오면 0 위치의 데이터가 지워집니다. |
호출에 필요한 권한
| 가져오기 |
요청 시 필수 매개변수
| Credentials, ImportDataOptions, Version, Sheet, RowData |
이 메서드의 요청에는 제공된 데이터 행을 수신할 시트와 버전을 결정하는 데 사용할 매개변수가 포함되어 있습니다. 이 방법을 사용하면 큐브의 위치로 값이 0인 항목을 가져와 큐브 시트에서 데이터를 삭제할 수도 있습니다. 0을 큐브 시트로 가져오면 0 위치의 데이터가 지워집니다.
요청 형식
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" 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"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Sales Cube" isUserAssigned="false" /> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|06/2014|07/2014|08/2014|09/2014|01/2015</header> <rows> <row>Coffee table|Argentina|Do-All 15 Vertical|Aeropostale|Price|Corporate Plan|0|0|0|0|0</row> </rows> </rowData> </call>
이 API 호출을 호출할 때마다 나열된 각 유형의 요소가 정확히 하나만 포함되어야 합니다.
- 자격증명
- importDataOptions
- 버전
- 시트
- rowData
또한 모드가 REPLACE로 지정된 경우 범위 요소를 지정해야 합니다.
헤더의 파이프 문자( | ) 수와 데이터가 일치하지 않으면 API v30 이상에서 오류가 발생합니다.
바꾸기 모드를 범위로 지정하는 샘플 요청:
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <version name="Budget 2022" isDefault="true" /> <sheet name="Expense Cube" isUserAssigned="false" /> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" mode="REPLACE" /> <!-- Scope parameter specifying the import scope.--> <scope> <!-- Specifies the time scope for import. All values will be specified as time codes.--> <time mode="EXPLICIT"> <timeRange start="01/2021" end="10/2021" /> </time> <!-- Specifies list of accounts in the scope. All values will be specified as code field.--> <accounts mode="EXPLICIT"> <account includeDescendants="true">Op_Expense_Inputs</account> <account includeDescendants="true">Op_Expense_Drivers</account> </accounts> <!-- Specifies list of levels in the scope. All values will be specified as code field.--> <levels mode="INPUT"/> </scope> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|01/2022|02/2022|03/2022|04/2022|05/2022|06/2022|07/2022|08/2022|09/2022|10/2022|11/2022|12/2022</header> <rows> <row>Coffee Table|Argentina|Do-All 15 Vertical|Aeropostale|Units|Development|44567.33|21345.77|22341.43|65567.32|298145.12|12641.83|77821.53|7766342.09|211441.21|88712.43|61940.41|662341.03|775420.25|800345.17</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 | 아니요 | 다음과 같은 경우에만 사용됩니다.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는 importCubeData가 예상해야 함을 나타냅니다. Account Code , Level Code , Dimension Code 및 Dimension Name Column 인스턴스에 대해 '표시명 사용'이 설정된 경우 페이로드에 포함displayNameEnabled=false는 인스턴스에 대해 '표시명 사용'이 켜져 있는 경우에도 importCubeData API가 v30 이전 API 계약을 계속 따라야 함을 나타냅니다. importCubeData API가 표시명 속성을 무시합니다. Account Code , Level Code , Dimension Code 및 Dimension Name Column .displayNameEnabled의 기본값은 'false'입니다. | false |
모드
API v32 이상에서 사용가능 | 아니요 | APPEND 또는 REPLACE 중 하나인 가져오기 모드를 지정합니다.
추가 - 기존 팩트가 업데이트되거나 새 팩트가 삽입됩니다. 팩트가 삭제되지 않습니다. REPLACE - 호출자는 데이터가 페이로드에 제공된 좌표로 대체될 큐브 좌표를 나타내는 범위 요소를 지정해야 합니다. 범위 내의 모든 기존 데이터가 호출 페이로드의 데이터로 바뀝니다. 이 옵션은 API v32 이상 버전에서 지원됩니다. 이전 버전에서 API를 호출하면 오류가 발생합니다. 지정되지 않은 경우 mode의 기본값은 APPEND입니다. | 바꾸기 |
요소의 콘텐츠 | |||
(없음) | |||
버전 요소
| |||
태그명
| 버전 | ||
설명
| 요청된 데이터를 수신하는 데 사용해야 하는 버전을 나타냅니다. 각 호출에 대해 버전을 제공해야 합니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
이름 | 아니요 | 데이터를 수신하는 데 사용할 버전의 이름입니다. 단일 API 호출 내에서는 하나의 버전에만 액세스할 수 있습니다. 이름을 입력하지 않으면isDefault 플래그를 으로 설정해야 합니다.이 요소는 true입니다. | 2012년 예산 |
isDefault | 아니요 | 호출자가 이름과 관계없이 인스턴스의 현재 기본 버전에 액세스하려는 경우 이 특성을 true로 설정할 수 있으며, 이 경우 태그의 name 특성(있는 경우)은 무시됩니다. 그렇지 않고 이 값이 false이거나 이 특성이 없는 경우, 이 호출이 성공하려면 제공된 이름을 사용하는 버전이 존재하고 사용자가 액세스할 수 있어야 합니다. | false |
요소의 콘텐츠
| |||
(없음) | |||
시트 요소
| |||
태그명
| 시트 | ||
설명
| 가져온 데이터를 수신해야 하는 시트를 나타냅니다. 각 API 호출은 하나의 시트 데이터만 대상으로 지정할 수 있습니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
이름 | 예 | 데이터를 가져올 시트의 이름입니다. | 직원 |
isUserAssigned | 아니요 | 시트가 사용자 지정 시트임을 나타냅니다. 지정하지 않으면 레벨 지정 시트임을 나타내는 false가 기본값으로 설정됩니다. | false |
요소의 콘텐츠
| |||
(없음) | |||
범위 요소
| |||
태그명
| 범위 | ||
설명
| 이 가져오기의 범위를 지정합니다. 가져오기 모드가 REPLACE로 지정된 경우에만 적용할 수 있습니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 범위에서 셀 메모를 지울지 여부를 지정합니다. 다음 3가지 열거 값 중 하나여야 합니다.
eraseCellNotes를 지정하지 않으면 NONE으로 기본 설정됩니다. | 없음 |
요소의 콘텐츠
| |||
하나의 시간 요소, 하나의 계정 요소 및 하나의 레벨 요소(모두 필수)입니다. | |||
시간 요소
| |||
태그명
| 시간 | ||
설명
| 가져오기를 위한 시간 범위를 나타내는 하나 이상의 시간 범위를 지정합니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 시간 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다.
모드가 지정되고 이 INPUT 또는 VERSION이면 timeRange 요소가 포함되지 않아야 합니다. 있는 경우 오류 조건으로 처리됩니다.
VERSION을 지정하면 계획 시작일이 버전 시작일 이후인 경우에도 버전 시작일이 고려됩니다. | 입력 |
요소의 콘텐츠
| |||
하나 이상의 timeRange 요소 - mode가 INPUT 또는 VERSION이 아닌 경우 | |||
timeRange 요소
| |||
태그명
| TimeRange | ||
설명
| 시간 범위에 대해 단일 시간 범위를 지정합니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
시작 | 예 | 가져오기 시간 범위의 시작 기간입니다. | 07/2021 |
종료 | 예 | 가져오기 시간 범위의 종료 기간 | 08/2021 |
요소의 콘텐츠
| |||
(없음) | |||
계정 요소
| |||
태그명
| 계정 | ||
설명
| 가져오기 범위의 계정 코드를 지정합니다. 여기에 계정 코드가 있지만 가져오기 데이터에 이 계정에 대한 데이터가 없는 경우, 이 계정의 데이터는 시간 범위 및 나머지 범위 좌표에 대해 제거됩니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 계정 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다.
모드가 지정되고 모드가 INPUT 또는 ALL이면 계정 하위 요소가 포함되지 않아야 합니다. 있는 경우 오류 조건으로 처리됩니다. | EXPLICIT |
요소의 콘텐츠
| |||
mode가 INPUT 또는 ALL이 아닌 경우 하나 이상의 계정 요소 | |||
계정 요소
| |||
태그명
| account | ||
설명
| 가져오기 범위에 포함할 계정 코드를 지정합니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
includeDescendants | 아니요 | 계정이 leaf 계정인 경우 includeDescendants는 영향을 주지 않습니다.
계정이 parent 계정인 경우 이 특성을 true로 지정하면 범위에 이 계정의 leaf descendant가 모두 포함됩니다. 계정이 parent 계정이고 includeDescendants가 false인 경우 이 계정 요소는 지정되지 않은 것처럼 처리됩니다. 이와 같이 parent 계정을 처리하는 이유는 leaf 계정이 parent 계정이 되도록 상태를 올리거나 이 변경사항을 반영하기 위해 가져오기 사양이 제때에 업데이트되지 않을 수 있기 때문입니다. includeDescendants=false인 parent 계정을 무시하면 의도하지 않은 데이터 삭제를 방지할 수 있습니다. 이는 옵션 특성이며 기본값은 false로 간주됩니다. | true |
요소의 콘텐츠
| |||
가져오기 범위의 일부로 사용되는 계정의 계정 코드를 지정합니다. 예: Operational_Expense | |||
레벨 요소
| |||
태그명
| 개 레벨 | ||
설명
| 가져오기 범위의 레벨 코드를 지정합니다. 여기에 레벨 코드가 지정되었지만 가져오기 데이터에 이 레벨에 대한 데이터가 없으면 시간 범위 및 나머지 범위 좌표에 대해 이 레벨의 데이터가 제거됩니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
모드 | 예 | 레벨 범위의 모드를 지정합니다. 다음 세 가지 옵션 중 하나여야 합니다.
모드가 지정되고 모드가 INPUT 또는 ALL이면 레벨 하위 요소가 포함되지 않아야 합니다. 있는 경우 오류 조건으로 처리됩니다. | 입력 |
요소의 콘텐츠
| |||
모드가 INPUT 또는 ALL로 지정되지 않은 경우 하나 이상의 레벨 요소 | |||
레벨 요소
| |||
태그명
| level | ||
설명
| 가져오기 범위에 포함할 레벨 코드를 지정합니다.
API v32 이상에서 사용가능 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
includeDescendants | 아니요 | 레벨이 parent 레벨인 경우 이 특성을 true로 지정하면 범위의 자체(전용 노드)를 포함하여 이 레벨의 모든 leaf descendant가 포함됩니다.
이는 옵션 특성입니다. 특성이 제공되지 않은 경우 기본값은 false입니다. 특성이 제공되지 않거나 false로 제공되고 지정된 레벨이 parent 레벨인 경우, 이는 가져오기에서 해당 레벨의 Only(예: Engineering Only) 노드를 범위로 간주함을 의미합니다. 레벨의 child 레벨은 다른 레벨 요소와 함께 명시적으로 지정되지 않는 한 범위에서 고려되지 않습니다. | true |
요소의 콘텐츠
| |||
가져오기 범위의 일부로 레벨의 레벨 코드를 지정합니다. 예: 개발 | |||
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="warning-no-data-imported-dimension-unmapped">Warning: Row 3 was not imported because Coffeee table is unmapped.</message> </messages> </response>
실패(컨텍스트 있음)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row"> <context> <col header="ProductFurniture" value="Coffee table" /> <col header="CountryRegion" value="" /> <col header="Account" value="Do-All 15 Vertical" /> <col header="Level" value="Aeropostale" /> <col header="06/2014" value="Price" /> <col header="07/2014" value="Corporate Plan" /> <col header="08/2014" value="0.0" /> <col header="09/2014" value="0.0" /> <col header="01/2015" value="0.0" /> </context> Row 1 is missing a value. </message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
실패(컨텍스트 없음)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row">Row 1 is missing a value.</message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
응답 요소
| |||
태그명
| 응답 | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
성공 | 예 | 둘 중 하나true 또는false - API 호출의 성공 여부를 나타냅니다. 성공한 호출의 경우에도 응답에 경고 메시지가 포함될 수 있습니다. | true |
요소의 콘텐츠
| |||
단일 옵션메시지 요소 | |||
메시지 요소
| |||
태그명
| 메시지 | ||
설명
| 하나 이상의 컨테이너메시지 요소 | ||
요소의 특성
| |||
(없음) | |||
요소의 콘텐츠
| |||
하나 이상메시지 요소 | |||
메시지 요소
| |||
태그명
| 메시지 | ||
설명
| 시스템에서 호출자에게 다시 전송되는 메시지를 나타냅니다. 메시지는 요청이 성공하지 못한 경우의 오류 메시지, 요청이 성공한 경우의 경고 메시지, 성공의 경우 확인 메시지에 사용됩니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
키 | 아니요 | 지정된 경우 키는 특정 메시지 또는 메시지 유형을 식별하는 방법이며, 클라이언트 프로그램에서 자동화된 오류 기록 및 복구를 위해 유용합니다. 메시지의 언어가 변경되더라도 다른 요청 로케일에서는 키는 변경되지 않습니다. 또한 향후에는 문구 조정 또는 용어 변경으로 인해 키가 변경되지 않을 것입니다. | invalid-attributevalueid |
요소의 콘텐츠
| |||
| |||
컨텍스트 요소
| |||
태그명
| 컨텍스트 | ||
설명
| 하나 이상의 col 요소에 대한 컨테이너입니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
없음 | |||
요소의 콘텐츠
| |||
하나 이상의 col 요소 | |||
열 요소
| |||
태그명
| 열 | ||
설명
| 메시지의 컨텍스트를 나타냅니다. 메시지를 생성하는 행을 식별할 수 있도록 헤더/값 쌍을 제공합니다. | ||
요소의 특성
| |||
특성명
| 필수
| 값
| 예:
|
헤더 | 예 | 열의 헤더입니다. | '계정' |
값 | 예 | 열의 값입니다. | "GL-29482-38233" |
요소의 콘텐츠
| |||
(없음) | |||