メインコンテンツにスキップ
Adaptive Planning
最終更新: 2024-09-20
importStandardData

importStandardData

API v40 で更新 (2024 年 9 月 13 日)
カテゴリ
データの送信
説明
標準科目にデータを挿入または置換します。
起動に必要な権限
すべての場所にインポート
データの消去 (置換モードをサポートする API v36 以上)
リクエストに応じてパラメータが必要
認証情報、ImportDataOptions、バージョン、RowData
includeDescendants
このメソッドのリクエストには、提供されたデータ行をどのバージョンが受け取るかを決定するパラメータが含まれています。科目がシートに配置されているかどうかにかかわらず、データは任意の標準科目 (総勘定元帳科目、カスタム科目、前提条件、為替レート) にインポートできます。
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 コールの各呼び出しには、リストされた各タイプの要素を 1 つずつ含める必要があります。
  • 認証情報
  • importDataOptions
  • バージョン
  • rowData
  • ヘッダー
  • 行
ヘッダー内のパイプ文字 (|) の数とデータとが一致しない場合、API v30 以上ではエラーが発生します。
API v36+ では、importDataOptions モード特性が置換の場合、適用範囲要素も指定する必要があります。
例: 置換モードのリクエスト
API v36+ でのみ使用可能です。
<?xml version='1.0' encoding='UTF-8'?> <call method="importStandardData" callerName="a string that identifies your client application"> <credentials login="nobody@company.com" password="password" instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" allowParallel="true" moveBPtr="false" useMappings="false" mode="replace" /> <version name="Budget 2011" isDefault="false" /> <scope> <accounts mode="explicit"> <account includeDescendants="false">30490</account> <account includeDescendants="false">70313</account> </accounts> <levels mode="explicit"> <level includeDescendants="false">Development</level> <level includeDescendants="true">Sales</level> </levels> <time mode="input" /> </scope> <rowData> <header>Account|Level|Split Label|Base Pay|CapitalAssetClass|Company|CountryRegion|01/2011</header> <rows> <row>30490|Asia Sales||120-150K|Furniture|ABC Cons|Washington|1</row> <row>70313|Development||100-120K|OtherEquipment|ABC Cons|Maharashtra|2</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 の場合、インポートは、各バージョンの実績を表示する期間に影響しません。この特性は、次の場合に偽に設定する必要があります。PlanOrActuals の設定は次のとおりです計画
false
allowParallel
あり
次の場合にのみ使用します。PlanOrActuals 特性の設定実績オンにした場合True の場合、このインスタンスに対してすでに別の実績またはトランザクションのインポートが処理されていても、インポートが続行されます。オンにした場合false の場合、このインスタンスに対して処理中の実績またはトランザクションのインポートがすでに存在する場合、インポートは失敗します。
false
useMappings
なし
行要素内で科目、計画、属性値のインポート マッピングを使用するかどうかを指定します。検討済デフォルトでは true。条件false の場合、使用すべき内部識別子: 科目はコードで識別され、組織と属性値は名前で識別されます。
false
includeContext
なし
メッセージにコンテキスト ブロックを含めることができるかどうかを指定します。値のタイプfalse (コンテキストを表示しない) または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」または「置換」) を指定します。
追加
既存のデータが更新されるか、新しいデータが追加されます。データは削除されません。
置換
リクエストには、データがペイロードで提供されたデータに置き換えられる超キューブの座標を表す適用範囲要素を含める必要があります。有効範囲内の既存のデータのうち、ペイロードに一致する座標がないデータは削除されます。
このモード属性は、API v36 以降のバージョンでサポートされます。mode="REPLANCE" を指定して以前のバージョンの API を呼び出すとエラーが発生します。
モードが指定されていない場合のモードのデフォルト値は Append です。
追加
エレメントの内容
(なし)
バージョン要素
タグ名
バージョン
説明
リクエストされたデータの受信に使用するバージョンを示します。呼び出しごとにバージョンを指定する必要があります。
要素の特性
特性名
必須?
値
例
名前
なし
データの受信に使用されるバージョンの名前。1 つの API コールでアクセスできるバージョンは 1 つだけです。名前が指定されていない場合、この要素の isDefault フラグを true に設定する必要があります。
換算通貨バージョンとその名前のリストを取得するには、include 要素で currencyVersions=true を指定してexportVersions リクエストを作成します。
2014 年予算
isDefault
なし
呼び出し元が名前に関係なく、インスタンスの現在のデフォルト バージョンにアクセスしたい場合、この特性は true に設定できます。その場合、タグの name 特性 (存在する場合) は無視されます。そうしないと、この値が false の場合、またはこの特性が存在しない場合、この呼び出しを成功させるためには、指定された名前のバージョンが存在し、ユーザーがアクセスできる必要があります。
false
エレメントの内容
(なし)
適用範囲要素
タグ名
適用範囲
API バージョン 36 以降でのみ使用可能です。
説明
このインポートの範囲を指定します。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
eraseCellNotes
なし
範囲内のセル メモを消去するかどうかを指定します。次の 3 つの列挙値のいずれかである必要があります。
None
- セル メモを消去しません。
ALL
- 範囲内のすべてのセル メモを消去します。
ModIFIED_Only
- インポートによって変更された範囲内のセルについてのセル メモを消去します。これには、データがインポートされた以前は空のセル、およびデータがクリアされたセルが含まれます。
eraseCellNotes が指定されていない場合は、デフォルトで "なし" が使用されます。
なし
エレメントの内容
1 つの
時間
要素、1 つの
科目
要素、1 つの
組織
要素。すべて必須です。
科目要素
タグ名
科目
API バージョン 36 以降でのみ使用可能です。
説明
インポート範囲の科目を指定します。指定された科目は存在するが、インポート データにこの科目のデータがない場合、この科目のデータは、その期間および残りのスコープ座標で削除されます。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
モード
あり
科目適用範囲のモードを指定します。次の 3 つのオプションのいずれかである必要があります。
Explicit
- このモードが指定されている場合、インポートの科目範囲を決定する 1 つまたは複数の科目サブ要素が表示されると想定されます。
入力
- このモードが指定されている場合、科目の適用範囲は、インポート データに含まれる一意の科目セットによって決定されます。
注: account mode="ALL" は、標準のインポート範囲では許可されていません。
明示
エレメントの内容
モードが
"入力"
の場合、<科目> サブ要素は存在しません。
モードが
"EXPLICIT"
の場合、1 つ以上の "<科目>" サブ要素が必要です。
モードが
"EXPLICIT"
で、<account> サブ要素内のいずれかの科目コードが無効な場合、<accounts> 要素全体、および拡張子は <適用範囲> が無効とみなされます。無効なコードごとにエラー メッセージが応答に含まれます。
科目要素
タグ名
account
API バージョン 36 以降でのみ使用可能です。
説明
インポートの範囲に含める科目コードを指定します。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
includeDescendants
なし
科目が最下位科目の場合、"includeDescendants" は何の影響も及ぼしません。
科目が親科目である場合、この特性を true と指定すると、この科目のすべての最下位子孫が範囲に含まれます。
科目が親科目で、"includeDescendants" が "false" であるとエラーになります。最下位科目にのみインポートできます。
これは任意の属性であり、デフォルト値は false であると見なされます。
true
セレクター
なし
科目要素のコンテンツ タイプを指定します。
  • コード科目要素のコンテンツは科目コードです。例:
    <account selector="code">30440</account>
    この例では、30440 は科目コードです。
  • タイプ科目要素の内容は科目タイプです。例:
    <account selector="type">GL</account>
    この例では、科目要素タイプはすべての GL 科目です。現在、標準インポートの科目タイプは "GL" と "CUS TO" のみがサポートされています。それ以外のコンテンツはすべてエラーになります。
セレクターのデフォルト値は code です。
エレメントの内容
インポート範囲の一部として使用される科目の大文字と小文字の科目コード。たとえば、AccountsPayable です。コードは空欄にできません。また、コードに対応する科目が存在している必要があります。この科目をシステム科目またはリンク元科目にすることはできません。科目が算出科目の場合、その科目のデータ入力オーバーライドが存在する必要があります。そうでない場合、無効とみなされます。
科目コードが無効な場合、<accounts> 要素全体、および延長により <適用範囲> が無効とみなされます。
組織要素
タグ名
組織
API バージョン 36 以降でのみ使用可能です。
説明
インポート範囲の組織コードを指定します。ここで組織コードが指定されているものの、インポート データにこの組織のデータがない場合、この組織のデータは、時間範囲および残りのスコープ座標から削除されます。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
モード
あり
組織適用範囲のモードを指定します。次の 3 つのオプションのいずれかである必要があります。
Explicit
- このモードが指定されている場合、インポートの組織の適用範囲を決定する 1 つまたは複数の <組織> 下位要素が表示されると想定されます。
入力
- このモードが指定されている場合、組織の適用範囲は、インポート データに含まれる一意の組織によって決定されます。
ALL
- このモードが指定されている場合、組織の適用範囲はすべてのインポート可能組織になります。
明示
エレメントの内容
mode が INPUT または ALL の場合、<組織> サブ要素は存在しません。
モードが "EXPLICIT" の場合、1 つ以上の "<組織>" サブ要素が必要です。
モードが "EXPLICIT" で、<組織> サブ要素内のいずれかの組織コードが無効な場合、その <組織> 要素全体、および延長上で <適用範囲> が無効とみなされます。無効なコードごとにエラー メッセージが応答に含まれます。
組織要素
タグ名
level
API バージョン 36 以降でのみ使用可能です。
説明
インポートの範囲に含める組織コードを指定します。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
includeDescendants
なし
組織が親組織である場合、この特性を true と指定すると、それ自体 ("限定" ノード) を含むこの組織のすべての最下位子孫が範囲に含まれます。
これは任意の属性です。
特性が指定されていない場合、デフォルト値は false になります。特性が指定されていないか、false として指定されており、指定された組織が親組織である場合、インポート時にその組織の "限定" ("エンジニアリングのみ") ノードが考慮されます。組織の子は、他の組織要素で明示的に指定されない限り、適用範囲に含まれません。
true
エレメントの内容
組織の大文字と小文字の区別のコードを指定します。たとえば、「<組織>開発/組織」などです。
組織コードに問題がある場合 (組織でコードが見つからない場合など)、<組織> 全体、および拡張子 <適用範囲> が無効とみなされます。無効なコードごとにエラー メッセージが応答に含まれます。
時間要素
タグ名
time
API バージョン 36 以降でのみ使用可能です。
説明
インポートの範囲を表す時間範囲を 1 つまたは複数指定します。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
モード
あり
時間範囲のモードを指定します。次の 3 つのオプションのいずれかを指定してください。
入力
- このモードが指定されると、時間範囲は の時間コードによって決定されます。
<header>
要素ヘッダーに 2 か月が含まれている場合、インポートの範囲はこの 2 か月になります。
Explicit
- このモードが指定されている場合、インポートの時間範囲を決定する timeRange サブ要素が 1 つ以上表示されると想定されます。
バージョン
- このモードが指定されている場合、時間範囲はバージョンの開始と終了 (最初の累積期間を含む) になります。
モードが INPUT または SIONVER の場合、timeRange サブ要素を使用することはできません。timeRange サブ要素が存在する場合、エラーとして扱われます。
入力
エレメントの内容
1 つ以上の timeRange 要素 (モードが INPUT または VERSION 以外)。
timeRange 要素
タグ名
timeRange
API バージョン 36 以降でのみ使用可能です。
説明
時間スコープの単一の時間範囲を指定します。
importDataOptions 要素のモード特性が置換されている場合にのみ使用できます。
要素の特性
特性名
必須?
値
例
開始
あり
インポート期間の開始期間。
07/2021
終了
あり
インポート期間の終了期間。
08/2021
エレメントの内容
1 つ以上の timeRange 要素 (モードが INPUT または VERSION 以外)。
rowData element
タグ名
rowData
説明
インポートするデータの行のコンテナです。
要素の特性
(なし)
エレメントの内容
正確に 1ヘッダー要素 - 正確に 1 つ行要素
ヘッダー要素
タグ名
ヘッダー
説明
対応するデータの列の名前と順序を指定します行要素
要素の特性
(なし)
エレメントの内容
縦棒で列名が区切られたテキスト行。列名は、シートの属性名やフィールド名、あるいはデータを含む期間コードと対応している必要があります。これらは、データのインポート先のシートのインポート テンプレートにある列名と同じで、各列ヘッダーは縦の棒またはパイプの記号で隣の列と区切られます。
表示名を有効にするインスタンスの場合、ヘッダーでは次の操作がサポートされません。
"<dimension>"
次の値との組み合わせ
"<dimension> Name"
または
"<dimension> Code"
Adaptive Planning でサポートされているロケールの API v30 以上。
行要素
タグ名
行
説明
1 つ以上のコンテナ行要素
要素の特性
(なし)
エレメントの内容
1 つ以上行要素
行要素
タグ名
row
説明
インポート中の単一行のデータ
要素の特性
(なし)
エレメントの内容
インポートされている単一行のフィールドのデータ。各フィールドの値は、縦棒またはパイプ記号で区切られます。データ フィールドは、ヘッダー要素の行と同じ順序である必要があります。値の数字が千単位の区切り文字を使用している場合、それらはリクエストの認証情報で指定されたロケールで使用されているカンマ区切り文字であると想定されます。

回答フォーマット

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

成功例

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