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

importConfigurableModelData

API v40 (2024 年 9 月 21 日) に更新。
カテゴリ
データの送信
説明
モデル シートのデータを挿入、置換、または更新します。
起動に必要な権限
インポート
リクエストに応じてパラメータが必要
認証情報、ImportDataOptions、バージョン、シート、RowData
このメソッドのリクエストにはパラメータが含まれており、指定されたデータ行をどのシートとバージョンで受け取るかを決定します。
この方法では、以下の処理が可能です。
  • シートに新しい行を追加する。
  • モデル シートに現在あるすべての行をインポートしたシートに置き換える。
  • シートのすべてのデータを置換 (インポートされた組織のみ)
  • インポートからの行をインポート キーと照合することによって、既存の行を更新する。
  • インポートからの行をインポート キーと照合することで既存の行を更新し、新しい行を追加します。
この API コールの各呼び出しには、リストされた各タイプの要素を 1 つずつ含める必要があります。
  • 認証情報
  • 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>

import Key で既存行を更新するためのリクエスト形式

<?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 が "計画" に設定されている場合、この属性は "false" に設定する必要があります。
false
allowParallel
あり
オンにした場合True の場合、このインスタンスに対してすでに別の実績またはトランザクションのインポートが処理されていても、インポートが続行されます。オンにした場合false の場合、このインスタンスに対して処理中の実績またはトランザクションのインポートがすでに存在する場合、インポートは失敗します。
false
useMappings
なし
行要素内で科目、計画、属性値のインポート マッピングを使用するかどうかを指定します。検討済デフォルトでは true。条件false の場合、使用すべき内部識別子: 科目はコードで識別され、組織と属性値は名前で識別されます。
false
replaceExisting
なし
"1" または "true" に設定すると、すべての組織のすべての既存の行が、インポートする新しい行に置き換えられます (つまり、すべての組織ですでに存在していたすべての行を消去)。このオプションは
、"すべての場所にインポート"
権限を持つユーザーのみが使用できます。
新しい行が重複している場合でも、インポートした行を既存の行に追加するには、"0" または "false" に設定します。
"2" に設定すると、モデル シートの既存の行が、インポートされる新しい行に置き換えられます。ただし、組織が保護された行のみが対象です。アップロードされたスプレッドシートに分割されていない行がない組織と保護された属性の組み合わせの行は、その行がアップロードによって置き換えられる行の分割でないかぎり、既存の行が削除されることはありません。
"replaceExisting" は、使用された属性と、データが同じ組織、科目、期間、バージョンに存在するかどうかを検証します。行キーが存在する場合は、行キーの列とも照合します。
システムの同じ場所にデータが存在する場合は、インポートして、それに置き換えます。この置換は、行ごとに行われます。インポートは一度にすべてを置き換えるわけではありません。一致しないインポート行がシートに追加されます。
たとえば、2 つのインポートを実行するとします。最初のインポート ファイルは、2 番目のインポート ファイルに含まれていないデータをロードします。既存のデータは 2 番目のインポート後も残ります。
特定の列のデータをすべて削除する場合、その列を含めるがその列の値を空白のままにします。メンションされていない列の列値は変更されません。
モデル シートの既存の行を更新してインポートする新しい行を反映するには、"3" に設定します。既存の行と一致する行がない場合、警告が返されます。このモードには import Key が必要です。
"分割を許可"
が選択されているシートは、更新をサポートしていません。
インポートする新しい行を反映するようにモデル シートの既存の行を更新し、既存の行と一致しない行に新しい行を挿入するには、"4" に設定します。このモードには import Key が必要です。新しい行を追加しない場合でも、"インポート キー"、"組織"、およびすべてのテキスト セレクターのみが必須列となります。
"分割を許可"
が選択されているシートは、更新をサポートしていません。
組織による置換のみの機能で、現在入力組織のみをサポートしている適用範囲に基づいて既存の行を置換するには、5 に設定します。新しい適用範囲要素を使用して適用範囲が提供されています。指定された範囲に一致する行のみが、インポート内のペイロードに置き換えられます。適用範囲と一致しない行は影響を受けません。
デフォルト値は true です。
true
importKey
なし
モデル シート行の更新時にインポート キーとして使用するモデル シート列名
Adaptive Planning
はインポート キー列を使用して、インポート内の各行をモデル シート内の行にマッチングさせます。すべての行のインポート キー値は一意である必要があります。
この属性は、replaceExisting が "3" または "4" の場合にのみ使用することができます。
インポート キー列は次のいずれかになります。
  • 組織列
  • 属性列
Level
includeContext
なし
メッセージにコンテキスト ブロックを含めることができるかどうかを指定します。値のタイプfalse (コンテキストを表示しない) またはtrue (該当する場合はコンテキストを表示)。指定しない場合、真であると想定されます。
false
displayNameEnabled
表示名が有効になっているインスタンスの API v31+ でのみ使用できます。
なし
displayNameEnabled=true は、インスタンスに対して "表示名の有効化" 設定がオンになっている場合、API がペイロードの科目コード、組織コード、属性コード、属性名列を想定する必要があることを示します。
displayNameEnabled=false は、インスタンスの "表示名の有効化" 設定がオンになっている場合でも、API は 30 日前の API 契約に従う必要があることを示します。
displayNameEnabled のデフォルト値は "false" です。
false
applyValidationRules
API v38 + でのみ使用できます。
なし
applyValidationRules=true は、API のバージョンが v38 以上である場合に、インポートされたすべてのデータに対してモデル シートのルール検証を API が実行することを示します。
applyValidationRules=false は、インポートされたすべてのデータのモデル シート ルール検証が API によって無視されることを示します。
applyValidationRules のデフォルト値は "true" です。
false
エレメントの内容
(なし)
バージョン要素
タグ名
バージョン
説明
リクエストされたデータの受信に使用するバージョンを示します。呼び出しごとにバージョンを指定する必要があります。
要素の特性
特性名
必須?
値
例
名前
なし
データの受信に使用されるバージョンの名前。1 つの API コールでアクセスできるバージョンは 1 つだけです。名前が指定されていない場合、isDefault フラグを次のように設定する必要がありますこの要素に対して true 。
2014 年予算
isDefault
なし
呼び出し元が名前に関係なく、インスタンスの現在のデフォルト バージョンにアクセスしたい場合、この特性は true に設定できます。その場合、タグの name 特性 (存在する場合) は無視されます。そうしないと、この値が false の場合、またはこの特性が存在しない場合、この呼び出しを成功させるためには、指定された名前のバージョンが存在し、ユーザーがアクセスできる必要があります。
false
エレメントの内容
(なし)
シート要素
タグ名
シート
説明
インポートしたデータを受信するシートを示します。各 API 呼び出しは、1 つのシートのデータのみを対象とすることができます。
要素の特性
特性名
必須?
値
例
名前
あり
データのインポート先のシート名
従業員
isUserAssigned
なし
シートがユーザー割当シートであることを示します。指定しない場合のデフォルト値は false で、組織割当シートであることを示します。
false
エレメントの内容
(なし)
スコープ要素
タグ名
Scope (API v40 で使用可能)
説明
このインポートの範囲を指定します。例:
<scope> <levels> mode="INPUT"/> </scope>
importDataOptions 要素のreplaceExisting特性が 5 の場合にのみ許可されます。
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"> <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>
回答エレメント
タグ名
回答
要素の特性
特性名
必須?
値
例
成功
あり
両方真またはfalse。API 呼び出しが成功したかどうかを示します。呼び出しが成功した場合でも、応答に警告メッセージが含まれる場合があります。
true
エレメントの内容
単一 (任意)メッセージ要素
メッセージ要素
タグ名
メッセージ
説明
1 つ以上のコンテナメッセージ要素
要素の特性
(なし)
エレメントの内容
1 つ以上メッセージ要素
メッセージ要素
タグ名
メッセージ
説明
システムから呼び出し元に送り返されるメッセージを表します。メッセージは、リクエストが成功しない場合のエラー メッセージ、リクエストが成功した場合の警告メッセージ、成功した場合の確認メッセージに使用されます。
要素の特性
特性名
必須?
値
例
キー
なし
キーを入力すると、特定のメッセージやメッセージのタイプを識別することができ、クライアント プログラムにおけるエラーの記録と復旧の自動化に役立ちます。メッセージの言語が変わってもキーはリクエストのロケールの中で変更されません。また、単語の調整や用語の変更によってキーが将来変更される可能性も低いです。
invalid-attributevalueid
エレメントの内容
  1. メッセージのテキスト。このテキストは、リクエストで指定されたロケールの言語になります (そのロケールがサポートされている場合)。テキストには、処理された行数や、エラーの原因となった特定の列や値などの可変情報を含めることもできます。
  2. 任意のコンテキスト要素。
コンテキスト要素
タグ名
context
説明
1 つ以上の列要素のコンテナです。
要素の特性
特性名
必須?
値
例
なし
エレメントの内容
1 つ以上の列要素
列要素
タグ名
col
説明
メッセージのコンテキストを示します。ヘッダーと値のペアを指定して、メッセージを生成している行を識別できるようにします。
要素の特性
特性名
必須?
値
例
ヘッダー
あり
列のヘッダー。
"科目"
値
あり
列の値。
"GL-29482-38233"
エレメントの内容
(なし)