updateAttributes
API v20 以上でサポート
カテゴリ | メタデータの変更 |
説明 | 既存の特性、その特性値、プロパティのセットを更新します。複数の特性値を持つ複数の特性は、1 回の呼び出しで更新できます。成功した場合、この API は更新または作成された特性の詳細を返します。API が失敗すると、エラーとその原因の包括的なリストが返されます。 |
起動に必要な権限 | モデル |
リクエストに応じてパラメータが必要 | 認証情報 |
このメソッドのリクエストには、呼び出し元のユーザーを識別し、認証するための認証情報タグが含まれています。ユーザーには "モデル" が指定されている必要があります 概念: 権限セット および更新する属性を管理するために必要な権限
ベスト プラクティス: exportAttributes を呼び出して
Adaptive Planning
updateAttributes リクエストに必要な特性 ID。exportAttributes の呼び出しと updateAttributes の呼び出しとの間の時間を短縮するために、最善を絞ってください。HTTP | 説明 |
|---|---|
Method | Post |
Content-Type | text/xml |
curl の例
curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20
updateAttributes.xml contents
リクエストのフォーマット
Update a set of existing attributes and their attribute values, and their <?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"/> <attributes proceedWithWarnings="0"> <attribute id="13" name="AP Eligible" type="account" keepSorted="1"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> </attribute> </attributes> </call>
ペイロードが多い場合は、圧縮 XML ファイル (ZIP 形式) を計上できます。その方法については、 こちらをご覧ください。
次の条件が updateAttributes に適用されます。
- 更新対象の特性は、内部 ID 番号によって識別されます。
- 新しい特性を作成するには、空白または空白の ID プロパティを指定してください。
- 既存の (新規ではない) アイテムを移動して、新しいアイテムの子にすることができます。これにより、新しいアイテムが作成され、既存のアイテムが子としてその下に移動します。
新規特性を作成するためのリクエスト形式
新しい特性を作成するには、次のようにします。
AP Eligible
、ID を空白のままにして、その名前とタイプを入力します。<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="" name="AP Eligible" type="account"> <attributeValue id="" name="No" /> <attributeValue id="" name="Yes"> <attributeValue id="" name="Full" /> <attributeValue id="" name="Partial" /> </attributeValue> </attribute> </attributes> </call>
リスト属性の新しい特性の作成に関するリクエスト
新しい特性を作成する場合
Education Type
リスト属性の場合 Education.
特性値 Technical
とその子 Tech1,
ID が空白: 新規である.
<?xml version="1.0" encoding="UTF-8"?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password" /> <attributes> <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1"> <attributeValue id="" name="Technical" description=""> <attributeValue id="" name="Tech1" description="" /> </attributeValue> <attributeValue id="" name="Management" description="" /> </attribute> </attributes> </call>
新規特性値を作成するためのリクエスト形式
future
次の値より下 AP Eligible
特性の次の値 id 13
および特性値 no
- 相手: id 118
では、以下を使用できます。<?xml version='1.0' encoding='UTF-8'?> <call method="updateAttributes" callerName="Steve C"> <credentials login="sampleuser@company.com" password="my_password"/> <attributes> <attribute id="13"> <attributeValue id="118" > <attributeValue id="" name="future" /> </attributeValue> </attribute> </attributes> </call> To create a new attribute value, include its parent by its ID. For example, to add a new attribute value
この方法では、特性に関する何もの変更も行われません
id 13
。新しい特性値を作成する future
- 特性 id 13
その親を特性値にする no
。次のすべての記載されていない特性値 no
値リストの最後に移動する。これは、新しい特性値に対して「親を設定する」ことと同じです。1 回の updateAttributes コールでの複数の名前変更の処理
リモート システム内の同一エンティティに対して複数の名称変更が発生する可能性があります。
updateAttributes
。リモート システムのエンティティ名は、同じエンティティ ID と交換できます。条件 updateAttributes
名前の交換後に呼び出しが発生する場合、 updateAttributes
呼び出しは、氏名変更全体の ID を追跡することによって、これらの変更を管理します。この呼び出しは、既存の名称を使用する新しい ID の導入を処理することもできます。それぞれの例が成功するには、固有の値を使って ID が完全に交換される必要があります。
例 1: リモート システムでの単純な名称交換。
To create a new attribute value, include its parent by its ID. For example, to add a new ID Unique Value New Unique Value 1 AA BB 2 BB AA
例 2: リモート システムでの 3 つの名前変更のシーケンス。
ID Unique Value New Unique Value 1 AA BB 2 BB CC 3 CC AA
例 3: 既存の一意値を使用した新しいエンティティ。
ID Unique Value New Unique Value 4 AA 1 AA BB 2 BB Old BB
認証情報要素 | |||
タグ名 | 認証情報 | ||
説明 | すべての API 呼び出しには、API を呼び出したユーザーを識別するための単一の認証情報要素が含まれている必要があります。その後、この API 呼び出しはこのユーザーとして実行されます (システムの監査証跡やアクション履歴は、このユーザーがアクションを実行したことを示します)。そのため、API 呼び出しが成功: | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
ログイン | あり | API メソッドを呼び出すユーザーのログイン名。このユーザーは、メソッドを呼び出すために必要な権限を持っている必要があります。 | sampleuser@company.com |
password | あり | API メソッドを呼び出すユーザーのパスワード。 | my_password |
ロケール | なし | 入力される数値と日付の解釈、および出力する数値と日付の形式設定 (適切な千単位の区切り文字、月名、日付の形式設定を使用) に使用されるロケールを指定します。ロケールは、応答内のシステム メッセージを表示する言語を指定するためにも使用されます。指定しない場合は、en_US (米国英語) が使用されます。 | fr_FR |
instanceCode | なし | 認証情報で指定されたユーザーが の複数のインスタンスにアクセスできる場合、 Adaptive Planning 、この属性は、ユーザーがデフォルトのインスタンス以外のインスタンスにアクセスしようとしていることを指定するのに使用できます。指定しない場合、ユーザーのデフォルトのインスタンスが使用されます。使用可能なインスタンス コードを決定するには、exportInstances API を使用します。 | MYINSTANCE1 |
エレメントの内容 | |||
(なし) | |||
特性要素 | |||
タグ名 | 特性 | ||
説明 | ペイロードごとに許可される属性要素のリクエストは 1 つだけです。これには、1 つ以上の特性要素が含まれます。 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
proceedWithWarnings | なし | 特性値の親を再設定する場合にのみ適用されます。 警告があり、proceedWithWarnings=0 の場合、attributeValue は更新されません。警告がある場合に attributeValue を更新するには、proceedWithWarnings=1 を設定します。 type=科目と type=組織にのみ適用されます。 ProceedWithWarnings=1 (a) 科目/組織特性のタグ付けとの互換性がなくなる場合でも、親の再設定が実行されます。 (b) 互換性のない科目/組織の特性のタグ付けはすべて、親の特性のタグ付けを使用して修正されます。 ProceedWithWarnings=0 は、特性値の親の再設定によって科目/組織の特性マッピングの互換性がなくなる場合にエラーが発生します。 | 1 |
retainExistingOrder API v27+ で使用可能 | なし | retainExistingOrder="1" は、updateAttributes API が XML ペイロード内の要素の順序を無視し、既存の定義済みの順序を保持することを示します。 tainExistingOrder="0" は、updateAttributes API が XML ペイロード内の他の兄弟と比較したタグの位置に基づいて要素の順序を更新する必要があることを示します。 特性で "keepSorted" フラグが有効になっている場合、"retainExistingOrder" フラグは無視されます。 retainExistingOrder のデフォルト値は "1" です。 | 1 |
DisplayNameEnabled
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | displayNameEnabled=1 は、updateAttributes が の表示名プロパティに従う必要があることを示します code , displayNameType 、および description インスタンスで "表示名の有効化" がオンの場合。displayNameEnabled=0 は、インスタンスで "表示名の有効化" がオンになっている場合でも、updateAttributes API が v30 前の API 契約に従うべきであることを示します。updateAttributes API は表示名プロパティを無視します code , displayNameType および description 。displayNameEnabled のデフォルト値は "0" です。 | 1 |
エレメントの内容 | |||
1 つまたは複数の特性要素を含みます。 | |||
特性要素 | |||
タグ名 | 特性 | ||
説明 | 作成または更新する特性を指定します。 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
ID | あり | 特性の内部システム ID 番号。 | 16 |
名前
API v30 で更新済 | あり | レポートおよびシートに表示される特性の名前。
| 流動資産 |
code
API v39+ で使用できます。 | なし | 特性のコード | 流動資産 |
displayNameType
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性値の表示を制御します。指定可能な値は、NAME、CODE、NAME_CODE、CODE_NAME です。
空白の場合または指定されていない場合は、デフォルトの NAME になります。 このプロパティは、インスタンスで "表示名の有効化" がオンになっている場合にのみ使用できます。 | "CODE_NAME" |
importAutoCreateValues | なし | "1" はこの特性の特性値がインポートによって作成できることを意味し、"0" (または指定されていない場合) は作成できないことを意味します。 | 1 |
type | なし | 特性が組織特性、科目特性、属性特性のいずれであるかを示します。 システムにまだ存在しない新しい特性を作成する場合は必須です。 更新操作によってタイプを変更することはできません。 | account |
listDimensionName | なし | 属性がフラット リスト属性であるかどうかを示します。 特性タイプ = 属性の場合にのみ適用されます。 "listDimensionName" は更新操作で変更することはできません。 | 色 |
keepSorted | なし | "1" は、この特性の値が常にアルファベット順にソートされていることを示します。 "0" (または指定されていない) は、リクエスト ペイロード内の位置に基づいて特性値をソートすることを意味します。 値が指定されていない場合のみ、作成操作でのみデフォルト値は "0" になります。 XML に親と、リストされていない階層特性値の兄弟が少なくとも 1 つ含まれている場合、リストされていない値は、更新中にリストされた兄弟の最後に移動します (親の子を並べ替える際、リストされた兄弟はすべて最初になります。 XML で指定された順序リストされていない兄弟はすべて、システムにおけるすでに設定されている順序で最後に配置されます。 "keepSorted" は各親特性値の子に適用されます。 "並べ替えを維持" が有効になっている場合、表示名のコンポーネントを変更すると、要素のソート順が変わる可能性があります。 | 1 |
shortName
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性の短い名前。最大文字数は 64 文字です。
インスタンスで "表示名の有効化" がオンになっている場合にのみ使用できます。 | 資産 |
説明
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性の説明。最大文字数は 2048 文字です。
デフォルト値: 空 このプロパティは、インスタンスで "表示名の有効化" がオンになっている場合にのみ使用できます。 | 資産 |
エレメントの内容 | |||
1 つ以上の attributeValue 要素 | |||
attributeValue 要素 | |||
タグ名 | attributeValue | ||
説明 | 作成または更新する特性値を指定します。 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
ID | なし | 特性値を識別します。 空白のままにした場合、リクエストによって新しい特性値が作成されることを示します。 | 24 |
code
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性値の一意のコード。
| はい |
名前
API v30 で更新済 | あり | シートおよびレポートに表示される特性値の名前。API v30 以上のインスタンスで "表示名の有効化" がオンの場合、名前の重複値が許可されます。インスタンスで "表示名の有効化" がオフになっている場合、コードを使用できないため、名前は一意である必要があります。 特性値の名前が無効です: この名前は (+) または (-) で終わります | はい |
説明 | なし | 特性値のテキストによる説明。 デフォルト値: 空 デフォルト値は、値が指定されなかった場合にのみ作成操作で使用されます。 | |
エレメントの内容 | |||
別の attributeValue を含めることができます。 | |||
回答フォーマット
<?xml version="1.0" encoding="UTF-8"?> <response success="true"> <messages> <message type="INFO">Attributes were saved successfully.</message> </messages> <output> <attributes> <attribute id="13" name="AP Eligible" type="account"> <attributeValue id="118" name="No" /> <attributeValue id="117" name="Yes"> <attributeValue id="136" name="Full" /> <attributeValue id="135" name="Partial" /> </attributeValue> </attribute> <attribute id="11" name="Product Line" type="account"> <attributeValue id="34" name="A" /> <attributeValue id="35" name="B" /> </attribute> <attribute id="9" name="Corporate Discount" type="level"> <attributeValue id="56" name="Available" /> <attributeValue id="54" name="Not Applicable" /> <attributeValue id="57" name="Not Available" /> <attributeValue id="55" name="TBD" /> </attribute> <attribute id="10" name="Tax Code" type="level"> <attributeValue id="146" name="TT-PYT" /> <attributeValue id="145" name="TT-TRE" /> </attribute> <attribute id="16" name="Industry" type="dimension" listDimensionName="Education"> <attributeValue id="335" name="Apparel"> <attributeValue id="354" name="Mens Apparel" /> <attributeValue id="355" name="Shoes" /> <attributeValue id="356" name="Womens Apparel" /> </attributeValue> </attribute> </attributes> </output> </response>
出力要素 | |
タグ名 | 出力 |
要素の特性 | |
(なし) | |
エレメントの内容 | |
単一の必須特性要素この出力ラベンダーはすべての API 応答の標準であり、成功した API 呼び出しの有効な出力を囲みます。 | |
特性要素 | |||
タグ名 | 特性 | ||
説明 | 0 個以上の特性要素のコンテナです。タグは、入力リクエストに基づいて順序付けされます。 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
proceedWithWarnings | なし | API リクエストで指定されたproceedWithWarnings値です。 | 1 |
retainExistingOrder | なし | updateAttributes=0 は、XML ペイロードの内容に基づいてソート順を更新します。 updateAttributes=1 は既存のソート順を保持します。 | 1 |
displayNameEnabled
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | displayNameEnabled=1 は、updateAttributes が の表示名プロパティに従う必要があることを示します code , displayNameType 、および description インスタンスで "表示名の有効化" がオンの場合。displayNameEnabled=0 は、インスタンスで "表示名の有効化" がオンになっている場合でも、updateAttributes API が 2021.42 より前の API 契約に従う必要があることを示します。updateAttributes API は表示名プロパティを無視します code , displayNameType および description 。displayNameEnabled のサポートは、2021.42 に開始されました。 displayNameEnabled のデフォルト値は "0" です。 | 1 |
エレメントの内容 | |||
1 つ以上の特性要素 | |||
特性要素 | |||||
タグ名 | 特性 | ||||
説明 | updateAttributes API コールへの応答で返される単一の特性を表します。 | ||||
要素の特性 | |||||
特性名 | 必須？ | 値 | 例 | ||
ID | あり | 特性の内部システム ID 番号。 | 16 | ||
名前 | あり | レポートおよびシートに表示される特性の名前。 | 流動資産 | ||
code
API v39+ で使用できます。 | あり | 特性のコード。 | 流動資産 | ||
shortName | 特性の短い名前。最大文字数は 2048 文字です。 | 資産 | |||
displayNameType
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性値の表示を制御します。指定可能な値は、NAME、CODE、NAME_CODE、CODE_NAME です。
空白の場合または指定されていない場合は、デフォルトの NAME になります。 このプロパティは、インスタンスで "表示名の有効化" がオンになっている場合にのみ使用できます。 | CODE_NAME | ||
importAutoCreateValues | なし | "1" はこの特性の特性値がインポートによって作成できることを意味し、"0" (または指定されていない場合) は作成できないことを意味します。 | 1 | ||
type | あり | 特性のタイプ。これは、特性が科目の場合は "科目"、特性が組織の場合は "組織"、属性の場合は "属性" になります。 | account | ||
listDimensionName | なし | 特性のタイプが "属性" の場合は、リスト属性の名前。 | 学歴 | ||
説明 | なし | "特性の管理" で入力された特性のテキスト説明 (存在する場合) | 合計流動資産 | ||
keepSorted | あり | "1" は、この特性の値が常にアルファベット順にソートされていることを示します。 "0" (または指定されていない) は、リクエスト ペイロード内の位置に基づいて特性値をソートすることを意味します。 XML に親と、リストされていない階層特性値の兄弟が少なくとも 1 つ含まれている場合、リストされていない値は、更新中にリストされた兄弟の最後に移動します (親の子を並べ替える際、リストされた兄弟はすべて最初になります。 XML で指定された順序リストされていない兄弟はすべて、システムにおけるすでに設定されている順序で最後に配置されます。 "keepSorted" は各親特性値の子に適用されます。 | 1 | ||
ステータス | あり | 更新後の特性値のステータス。警告とエラーの場合は、メッセージ要素にメッセージ内容が含まれます。更新ステータスはメッセージ内容を返しません。
| 更新 | ||
message | なし | 特性入力に関するエラー メッセージ。 | 属性 "業種" は、ペイロードで重複しているか、ID 8 でシステムにすでに存在しています | ||
エレメントの内容 | |||||
ゼロ以上の任意の attributeValue 要素囲まれたattributeValue 要素はそれぞれ、特性の「ルート特性値」、つまり親値を持たない値を表します。 | |||||
attributeValue 要素 | |||
タグ名 | attributeValue | ||
説明 | updateAttributes API コールの応答で返される特性の単一メンバー値を表します。 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
ID | あり | 特性のこのメンバー値の内部システム ID 番号。 | 34 |
code
表示名を有効にしたインスタンスの API v30 以上でのみ使用できます。 | なし | 特性値の一意のコード。 | 使用可能 |
名前 | あり | 特性ページの管理に表示される特性のメンバー値のラベル。 | 使用可能 |
shortName | なし | 特性値の短い名前。 | 平均 |
説明 | なし | 特性値の説明。 デフォルト値: 空 デフォルト値は、値が指定されなかった場合にのみ作成操作で使用されます。 | |
propogateToDescendants | なし | 変更がこの組織の子に伝達されるかどうかを示します。いいえ: 0、はい: 1。 | 0 |
ステータス | あり | 更新後の特性のステータス。警告とエラーの場合は、メッセージ要素にメッセージ内容が含まれます。更新ステータスはメッセージ内容を返しません。
| 更新されました |
message | なし | 無効な attributeValue を入力した場合のエラー メッセージ | |
エレメントの内容 | |||
ゼロ以上の任意の attributeValue 要素囲まれたattributeValue 要素はそれぞれこの特性値の「子特性値」を表し、そのメンバーは暗黙的にこの値にロールアップされます。 | |||