メインコンテンツにスキップ
Adaptive Planning
最終更新: 2023-06-23
importCubeData

importCubeData

カテゴリ
データの送信
説明
キューブ シートでデータを挿入または置換します。この方法は、キューブ内の位置にゼロをインポートすることによって、キューブ シートからデータを削除するために使用することもできます。キューブ シートにゼロをインポートすると、ゼロの位置のデータが消去されます。
起動に必要な権限
インポート
リクエストに応じてパラメータが必要
Credentials, ImportDataOptions, Version, Sheet, RowData
このメソッドのリクエストにはパラメータが含まれており、指定されたデータ行をどのシートとバージョンで受け取るかを決定します。この方法は、キューブ内の位置にゼロをインポートすることによって、キューブ シートからデータを削除するために使用することもできます。キューブ シートにゼロをインポートすると、ゼロの位置のデータが消去されます。

リクエストのフォーマット

<?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 コールの各呼び出しには、リストされた各タイプの要素を 1 つずつ含める必要があります。
  • 認証情報
  • importDataOptions
  • バージョン
  • シート
  • rowData
また、モードが "置換" に指定されている場合は、適用範囲要素を指定する必要があります。
ヘッダー内のパイプ文字 (|) の数とデータとが一致しない場合、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
password
あり
API メソッドを呼び出すユーザーのパスワード。
my_password
ロケール
なし
受信番号と日付の解釈、および送信番号と日付の形式設定 (適切な千単位の区切り文字を使用) に使用するロケールを指定します。期間名、日付の形式設定)。ロケールは、応答内のシステム メッセージを表示する言語を指定するためにも使用されます。指定しない場合は、en_US (米国英語) が使用されます。
fr_FR
instanceCode
なし
認証情報で指定されたユーザーが Adaptive Planning の複数のインスタンスにアクセスできる場合、この属性を使用して、ユーザーがデフォルトのインスタンス以外のインスタンスにアクセスしようとしていることを指定できます。指定しない場合、ユーザーのデフォルトのインスタンスが使用されます。使用可能なインスタンス コードを決定するには、exportInstances API を使用します。
MYINSTANCE1
エレメントの内容
(なし)
importDataOptions element
タグ名
importDataOptions
説明
インポートの実行時に使用するオプションを指定します。
要素の特性
特性名
必須?
planOrActuals
あり
次のいずれかに設定してください:プラン" または "実績": インポートするデータのタイプを指定します。この設定が で指定されたバージョンと競合する場合、バージョン タグバージョン タグの値が優先され、この設定は無視されます。
計画
moveBPtr
なし
次の場合にのみ使用します。PlanOrActuals 特性の設定実績条件moveBPtr は次のように設定されていますtrue の場合、インポートによって、実績バージョンの実績の可用性のポインターが、インポートされたデータで見つかった最新の期間に移動します。オンにした場合false の場合、インポートは、各バージョンの実績を表示する期間に影響しません。この特性は、次の場合に偽に設定する必要があります。PlanOrActuals の設定は次のとおりです計画
false
allowParallel
あり
次の場合にのみ使用します。PlanOrActuals 特性の設定実績オンにした場合True の場合、このインスタンスに対してすでに別の実績またはトランザクションのインポートが処理されていても、インポートが続行されます。オンにした場合false の場合、このインスタンスに対して処理中の実績またはトランザクションのインポートがすでに存在する場合、インポートは失敗します。
false
useMappings
なし
行要素内で科目、計画、属性値のインポート マッピングを使用するかどうかを指定します。検討済デフォルトでは true。条件false の場合、使用すべき内部識別子: 科目はコードで識別され、組織と属性値は名前で識別されます。
false
includeContext
なし
メッセージにコンテキスト ブロックを含めることができるかどうかを指定します。値のタイプfalse (コンテキストを表示しない) または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" または "置換") を指定します。
追加 - 既存のデータが更新されるか、新しいデータが挿入されます。データは削除されません。
置換: 呼び出し元は、データがペイロードで提供されたものと置き換えられるキューブの座標を表す適用範囲要素を指定する必要があります。スコープ内の既存のデータはすべて、呼び出しのペイロード内のデータに置き換えられます。
このオプションは、API v32 以降のバージョンでサポートされています。前のバージョンで API を呼び出すとエラーが発生します。
モードが指定されていない場合のモードのデフォルト値は Append です。
置換
エレメントの内容
(なし)
バージョン要素
タグ名
バージョン
説明
リクエストされたデータの受信に使用するバージョンを示します。呼び出しごとにバージョンを指定する必要があります。
要素の特性
特性名
必須?
名前
なし
データの受信に使用されるバージョンの名前。1 つの API コールでアクセスできるバージョンは 1 つだけです。名前が指定されていない場合、isDefault フラグを次のように設定する必要がありますこの要素に対して true 。
2012 年予算
isDefault
なし
呼び出し元が名前に関係なく、インスタンスの現在のデフォルト バージョンにアクセスしたい場合、この特性は true に設定できます。その場合、タグの name 特性 (存在する場合) は無視されます。そうしないと、この値が false の場合、またはこの特性が存在しない場合、この呼び出しを成功させるためには、指定された名前のバージョンが存在し、ユーザーがアクセスできる必要があります。
false
エレメントの内容
(なし)
シート要素
タグ名
シート
説明
インポートしたデータを受信するシートを示します。各 API 呼び出しは、1 つのシートのデータのみを対象とすることができます。
要素の特性
特性名
必須?
名前
あり
データのインポート先のシート名
従業員
isUserAssigned
なし
シートがユーザー割当シートであることを示します。指定しない場合のデフォルト値は false で、組織割当シートであることを示します。
false
エレメントの内容
(なし)
適用範囲要素
タグ名
適用範囲
説明
このインポートの範囲を指定します。インポートのモードが "置換" に指定されている場合にのみ適用されます。
API v32+ で使用可能
要素の特性
特性名
必須?
モード
あり
範囲内のセル メモを消去するかどうかを指定します。次の 3 つの列挙値のいずれかである必要があります。
  • None - セル メモを消去しません。
  • ALL - 範囲内のすべてのセル メモを消去します。
  • ModIFIED_Only - インポートによって変更された範囲内のセルについてのセル メモを消去します。これには、データがインポートされた以前は空のセル、およびデータがクリアされたセルが含まれます。
eraseCellNotes が指定されていない場合は、デフォルトで "なし" が使用されます。
なし
エレメントの内容
1 つの時間要素、1 つの科目要素、1 つの組織要素。すべて必須です。
時間要素
タグ名
Time
説明
インポートの範囲を表す時間範囲を 1 つまたは複数指定します。
API v32+ で使用可能
要素の特性
特性名
必須?
モード
あり
時間範囲のモードを指定します。次の 3 つのオプションのいずれかを選択してください:
  • 入力 - このモードが指定されている場合、時間範囲は <header> 要素の時間コードによって決定されます。ヘッダーに 2 か月が含まれている場合、インポートの範囲はこの 2 か月になります。
  • Explicit - このモードが指定されている場合、インポートの時間範囲を決定する timeRange サブ要素が 1 つ以上表示されると想定されます。
  • バージョン - このモードが指定されている場合、時間範囲はバージョンの開始と終了 (最初の累積期間を含む) になります。
モードが指定されており、INPUT または VERSION の場合、timeRange 要素を含めることはできません。存在する場合、エラー条件として扱われます。
VERSION を指定すると、計画の開始日がバージョンの開始日より後であってもバージョンの開始日が考慮されます。
入力
エレメントの内容
1 つ以上の timeRange 要素 (モードが INPUT または VERSION 以外)。
timeRange 要素
タグ名
TimeRange
説明
時間スコープの単一の時間範囲を指定します。
API v32+ で使用可能
要素の特性
特性名
必須?
開始
あり
インポート期間の開始期間。
07/2021
終了
あり
インポート期間の終了期間。
08/2021
エレメントの内容
(なし)
科目要素
タグ名
科目
説明
インポート範囲の科目コードを指定します。ここに科目コードは存在するが、インポート データにこの科目のデータがない場合、この科目のデータは、その期間および残りのスコープ座標で削除されます。
API v32+ で使用可能
要素の特性
特性名
必須?
モード
あり
科目適用範囲のモードを指定します。次の 3 つのオプションのいずれかである必要があります。
  • Explicit - このモードが指定されている場合、インポートの科目範囲を決定する 1 つまたは複数の科目サブ要素が表示されると想定されます。
  • 入力 - このモードが指定されている場合、科目の適用範囲は、インポート データに含まれる一意の科目セットによって決定されます。
  • ALL - このモードが指定されている場合、科目の適用範囲はインポートのすべての科目になります。キューブ シートのインポートの場合、これはそのキューブ シートのすべてのインポート可能科目を表します。
モードが指定されており、INPUT または ALL の場合、科目下位要素を含めることはできません。存在する場合、これはエラー条件として扱われます。
明示
エレメントの内容
モードが INPUT または ALL でない場合は、1 つ以上の科目要素です。
科目要素
タグ名
account
説明
インポートの範囲に含める科目コードを指定します。
API v32+ で使用可能
要素の特性
特性名
必須?
includeDescendants
なし
科目が最下位科目の場合、"includeDescendants" は何の影響も及ぼしません。
科目が親科目である場合、この特性を true と指定すると、この科目のすべての最下位子孫が範囲に含まれます。
科目が親科目であり、includeDescendants が false の場合、この科目要素は指定されていないものとして扱われます。
親科目をこのように処理する理由は、最下位科目が親科目になるようにプロモーションされる場合があるためです。この変更を反映するためにインポート仕様が更新されるのが遅い場合があります。includeDescendants=false の場合、親科目を無視することで、誤ったデータの削除を防ぐことができます。
これは任意の属性であり、デフォルト値は false であると見なされます。
エレメントの内容
インポート範囲の一部として使用される科目の科目コードを指定します。たとえば、"業務経費" です。
組織要素
タグ名
組織
説明
インポート範囲の組織コードを指定します。ここで組織コードが指定されているものの、インポート データにこの組織のデータがない場合、この組織のデータは、時間範囲および残りのスコープ座標から削除されます。
API v32+ で使用可能
要素の特性
特性名
必須?
モード
あり
組織適用範囲のモードを指定します。次の 3 つのオプションのいずれかである必要があります。
  • Explicit - このモードが指定されている場合、インポートの組織適用範囲を決定する 1 つまたは複数の組織サブ要素が表示されると想定されます。
  • 入力 - このモードが指定されている場合、組織の適用範囲は、インポート データに含まれる一意の組織によって決定されます。
  • ALL - このモードが指定されている場合、組織の適用範囲はすべてのインポート可能組織になります。
モードが指定されており、INPUT または ALL の場合、組織のサブ要素を含めることはできません。存在する場合、これはエラー条件として扱われます。
入力
エレメントの内容
モードが INPUT または ALL として指定されていない限り、1 つ以上の組織要素
組織要素
タグ名
level
説明
インポートの範囲に含める組織コードを指定します。
API v32+ で使用可能
要素の特性
特性名
必須?
includeDescendants
なし
組織が親組織である場合、この特性を true と指定すると、自身 ("限定" ノード) を含むこの組織のすべての最下位子孫が範囲に含まれます。
これは任意の属性です。
特性が指定されていない場合、デフォルト値は false になります。特性が指定されていないか、false として指定されており、指定された組織が親組織である場合、インポート時にその組織の "限定" ("エンジニアリングのみ") ノードが考慮されます。組織の子は、他の組織要素で明示的に指定されない限り、適用範囲の対象外となります。
エレメントの内容
インポート範囲の一部として組織の組織コードを指定します。たとえば、「開発」です。
rowData element
タグ名
rowData
説明
インポートするデータの行のコンテナです。
要素の特性
(なし)
エレメントの内容
正確に 1ヘッダー要素 - 正確に 1 つ行要素
ヘッダー要素
タグ名
ヘッダー
説明
対応するデータの列の名前と順序を指定します行要素
要素の特性
(なし)
エレメントの内容
縦棒で列名が区切られたテキスト行。列名は、シートの属性名やフィールド名、あるいはデータを含む期間コードと対応している必要があります。これらは、データのインポート先のシートのインポート テンプレートにある列名と同じで、各列ヘッダーは縦の棒またはパイプの記号で隣の列と区切られます。
表示名を有効にするインスタンスの場合、ヘッダーでは次の操作がサポートされません。
"<dimension>"
次の値との組み合わせ
"<dimension> Name"
または
"<dimension> Code"
Adaptive Planning でサポートされているロケールの API v30 以上。
行要素
タグ名
説明
1 つ以上のコンテナ行要素
要素の特性
(なし)
エレメントの内容
1 つ以上行要素
行要素
タグ名
説明
インポート中の単一行のデータ
要素の特性
(なし)
エレメントの内容
インポートされている単一行のフィールドのデータ。各フィールドの値は、縦棒またはパイプ記号で区切られます。データ フィールドは、ヘッダー要素の行と同じ順序である必要があります。値の数字が千単位の区切り文字を使用している場合、それらはリクエストの認証情報で指定されたロケールで使用されているカンマ区切り文字であると想定されます。

回答フォーマット

これらは、キューブ データのインポートが成功した場合および失敗した場合の応答の例です。

成功例

<?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>
回答エレメント
タグ名
response
要素の特性
特性名
必須?
成功
あり
両方真またはfalse。API 呼び出しが成功したかどうかを示します。呼び出しが成功した場合でも、応答に警告メッセージが含まれる場合があります。
true
エレメントの内容
単一 (任意)メッセージ要素
メッセージ要素
タグ名
メッセージ
説明
1 つ以上のコンテナメッセージ要素
要素の特性
(なし)
エレメントの内容
1 つ以上メッセージ要素
メッセージ要素
タグ名
message
説明
システムから呼び出し元に送り返されるメッセージを表します。メッセージは、リクエストが成功しない場合のエラー メッセージ、リクエストが成功した場合の警告メッセージ、成功した場合の確認メッセージに使用されます。
要素の特性
特性名
必須?
キー
なし
キーを入力すると、特定のメッセージやメッセージのタイプを識別することができ、クライアント プログラムにおけるエラーの記録と復旧の自動化に役立ちます。メッセージの言語が変わってもキーはリクエストのロケールの中で変更されません。また、単語の調整や用語の変更によってキーが将来変更される可能性も低いです。
invalid-attributevalueid
エレメントの内容
  • メッセージのテキスト。このテキストは、リクエストで指定されたロケールの言語になります (そのロケールがサポートされている場合)。テキストには、処理された行数や、エラーの原因となった特定の列や値などの可変情報を含めることもできます。
  • 任意のコンテキスト要素。
コンテキスト要素
タグ名
context
説明
1 つ以上の列要素のコンテナです。
要素の特性
特性名
必須?
なし
エレメントの内容
1 つ以上の列要素
列要素
タグ名
col
説明
メッセージのコンテキストを示します。ヘッダーと値のペアを指定して、メッセージを生成している行を識別できるようにします。
要素の特性
特性名
必須?
ヘッダー
あり
列のヘッダー。
"Account"
あり
列の値。
"GL-29482-38233"
エレメントの内容
(なし)