customReportValues
API v37 で更新されました。
カテゴリ | データ取得 |
説明 | リクエストされたインスタンス内のリクエストされたレポート条件のデータ セットを返します。 |
起動に必要な権限 | なし (ユーザーに権限セットが割り当てられている必要があります) |
リクエストに応じてパラメータが必要 | 認証情報、レポート |
API バージョン 15 以降の場合は、exportTime を呼び出して正しい時間要素 ID を取得してください
2023R2 でリリースされた API v36 対応のパフォーマンスと拡張性の改善をリクエストで活用する方法については 、参考: customReportValues Performance Conditions を 参照してください。
このメソッドのリクエストには、データの検索や値の返しに使用されるレポートの仕様が含まれています。API は内部 ID 番号を入力として取ります。メタデータ取得 API は、有効な ID を取得するために呼び出すことができます。結果はコードと値で表されます。必要に応じて、応答に警告やエラー メッセージも返されます。
この API はマトリクス レポートに基づいています。このリクエストでは、呼び出し元が X 軸 (列)、Y 軸 (行)、および API によって取得されたすべてのデータのフィルタに使用されるオプションのフィルタ軸の要素を指定する必要があります。マトリクス レポートには、レポートに表示されるデータを決定する軸が含まれています。各軸はレポートの端を定義します。すべてのマトリクス レポートには次の 3 つの軸があります。
- X 軸 (上の端)レポートの列のセットを定義します。
- Y 軸 (左端)。レポート上の行のセットを定義します
- フィルタ軸: レポートのすべてのデータに適用されるプロパティを定義するグローバル軸。詳しくはフィルタ軸の例を参照してください。
軸は複数のセグメントに分割できます。セグメントは、単一の軸上の属性のセットを分割する方法です。フィルタ軸に含めることができるセグメントは 1 つのみですが、他の 2 つの軸は必要な数のセグメントを含めることができます。
各セグメントに含めることができる層の数に制限はありません。層は、その属性のどの要素がその下の行または列に適用されるかを記述するために使用される単一の論理属性を表します。セグメントには、論理属性ごとに最大 1 つの層しか含めることができません。
各層には、層の属性の 1 つまたは複数の要素を含めることができます。(層内のすべての要素は、層で指定された属性に属している必要があります。)要素は通常、科目属性の特定科目や時間属性の会計四半期など、属性の項目です。これらの要素は、レポート上で検出されたデータを選択および集計するためにシステムによって使用されます。
X 軸または Y 軸上のセグメントが複数の層を含む場合、各層の要素は他のすべての層のすべての要素と組み合わされて、層要素の可能性のあるすべての組み合わせのデカルト積が作成されます。各列または行は、各層から 1 つの要素を選択した、要素の 1 つの組み合わせを表します。たとえば、X 軸上のセグメント (上部にある列) が 5 つの要素を持つ層と 2 つの要素を持つ第 1 層である場合、セグメントは 10 個の個別の列となり、これは の要素のあらゆる可能な組み合わせを表します。階層要素タイプを複数の軸に配置することはできません。たとえば、科目要素タイプを行に配置した場合、それから列またはフィルタに科目を追加することはできません。
層は個々の要素または合計要素の両方を持つことができます。合計要素は、その下に指定されたすべての要素を任意に合計します。合計要素はフィルタで使用できません。
フィルタ軸は X 軸および Y 軸と非常に似ていますが、1 つのわずかな違いがあります。フィルタ軸はレポート内のすべてのデータに適用されるため、その層を組み合わせて複数の行や列を構成することはできません。代わりに、フィルタ軸は各層のすべての要素を結合し、すべての要素のデータを、それらの要素が単一の集計にロールアップされているかのように集計します。
参照 基本的なマトリクス レポートの作成 セグメント、軸、属性要素の詳細については、 を参照してください。
フィルタ軸の例
下の例は、フィルタ軸について考えられるすべての要素を示しています。
<axis type="FILTER"> <segment> <!-- Account filter --> <tier type="acct"> <el id="258" /> </tier> <!-- Time filter --> <tier type="time"> <el id="342" /> </tier> <!-- Level filter --> <tier type="lvl"> <el id="354" /> </tier> <!-- Version filter --> <tier type="ver"> <el id="385" offset="1" offset-strata="2"/> </tier> <!-- Currency filter --> <tier type="cur"> <el id="448" /> </tier> <!-- Account Attribute filter --> <tier entity-id="23" type="aAttr"> <el id="512" /> </tier> <!-- Level Attribute filter --> <tier entity-id="25" type="lAttr"> <el id="607" /> </tier> <!-- Dimension Attribute filter --> <tier entity-id="21" type="dAttr"> <el id="649" /> </tier> <!-- Dimension filter --> <tier entity-id="1" type="dim"> <el id="717" /> </tier> </segment> </axis>
リクエストのフォーマット
リクエストの XML スキーマは、customReportValues REST Specific にあります。
<?xml version='1.0' encoding='UTF-8'?> <call method="customReportValues" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" locale="fr_FR" instanceCode="INSTANCE1"></credentials> <requestInfo> <!-- Add elements here that we want to show up in the ELK logs --> </requestInfo> <report suppress-zeroes="1" include-element-code="1"> <!-- Run report suppressing blanks, but not zero values. Add calc element codes to the response --> <!-- columns --> <axis type="X"> <segment> <!-- time columns --> <tier type="time"> <!-- Timespan creates multiple time columns from Jan-2014 to Dec-2014.Ids specified in timespan element are retrieved from exportTime API output. 'show-time' is a mandatory attribute specifying list of strata ids --> <el complex-type="timespan" end="179001" start="168001" show-time="3,2,1"/> <el id="180001" /> <!-- single column of Jan 2015 . This id is retrieved from exportTime API output--> <subtotal code="Subtotal" /> <!-- subtotal of the output of all the time elements left of this subtotal element --> </tier> </segment> </axis> <!-- rows --> <axis type="Y"> <segment> <!-- There are 2 tiers with 2 elements and 4 elements, respectively. Without considering expansion, this generates 8 rows of: 1. dimension value with id 135, account with id 51 2. dimension value with id 135, account with id 53 3. dimension value with id 135, difference between account with id 51 and account with id 53 4. dimension value with id 135, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row 5. dimension value with id 199, account with id 51 6. dimension value with id 199, account with id 53 7. dimension value with id 199, difference between account with id 51 and account with id 53 8. dimension value with id 199, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row. Assume dimension value 135 has child 150, which has children 160,161,162. Dimension value 199 has child 200, which has children 210,211,212. With expansion, element of dimension value 135 with rollup-mode 'D' and 'suppress-elt-rollup' would yield to {135,160,161,162}. Element of dimension value 199 with 'rollup-mode' 'X' and 'start-expanded' 199,200 would yield to {199,200,210,211,212}. In total, there will be 9 x 4 = 36 rows in cartesian without suppress zero. --> - <tier entity-id="13" type="dim"> <!-- dimension values with id 135 and 199 from dimension with id of 13 --> <el id="135" rollup-mode="D" suppress-elt-rollup="1"/> <!-- Expand to Leaves operation on tag dimension id=135, return "Leaves + root" --> <el id="199" rollup-mode="X" start-expanded="199,200"/> <!-- Custom expansion with start expanded on tag dimension id=199 and 200, where 200 is a child of 199, return 199 and the the immediate children of 199 and 200 --> </tier> <tier type="acct"> <!-- account with id of 51 and 53 --> <el id="51" /> <el id="53" /> <diff operand-a="51" operand-b="53" code="Difference" /> <!-- difference between account with id 51 and account with id 53 --> <calc formula="[51]+RPT.Difference" /> <!-- calculation using the formula - Sum of account with id 51 and the output of the difference element (previous element) --> </tier> </segment> </axis> </report> </call>
この API コールの各呼び出しには、リストされた各タイプの要素を 1 つずつ含める必要があります。
認証情報
レポート
認証情報要素 | |||
タグ名 | 認証情報 | ||
説明 | すべての API 呼び出しには、API を呼び出したユーザーを識別するための単一の認証情報要素が含まれている必要があります。その後、この API 呼び出しはこのユーザーとして実行されます (システムの監査証跡やアクション履歴は、このユーザーがアクションを実行したことを示します)。そのため、API 呼び出しが成功: | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
ログイン | あり | API メソッドを呼び出すユーザーのログイン名。このユーザーは、メソッドを呼び出すために必要な権限を持っている必要があります | sampleuser@company.com |
以下 | あり | API メソッドを呼び出すユーザーのパスワード。 | my_password |
ロケール | なし | 入力される数値と日付の解釈、および出力する数値と日付の形式設定 (適切な千単位の区切り文字、月名、日付の形式設定を使用) に使用されるロケールを指定します。ロケールは、応答内のシステム メッセージを表示する言語を指定するためにも使用されます。指定しない場合は、en_US (米国英語) が使用されます。 | fr_FR |
instanceCode | なし | 認証情報で指定されたユーザーが の複数のインスタンスにアクセスできる場合、 Adaptive Planning 、この属性は、ユーザーがデフォルトのインスタンス以外のインスタンスにアクセスしようとしていることを指定するのに使用できます。指定しない場合、ユーザーのデフォルトのインスタンスが使用されます。使用可能なインスタンス コードを決定するには、exportInstances API を使用します。 | MYINSTANCE1 |
エレメントの内容 | |||
(なし) | |||
レポート要素 | |||||||||||
タグ名 | レポート | ||||||||||
説明 | レポートを構成する要素を指定します。 | ||||||||||
要素の特性 | |||||||||||
特性名 | 必須？ | 値 | 例 | ||||||||
suppress-zeroes
API v37 で更新されました。 | なし | この特性は、行レベルで抑制を制御します。これを指定することで、出力にゼロや空白の行が含まれるかどうかを制御します。有効な値は、0 (何も表示しない - すべての行を表示)、1 (空白の表示 - 空白のセルのみを含む行を表示しない)、2 (空白の表示しない、ゼロ - 空白のセルまたはゼロのセルのみを含む行を表示しない) です。この属性が指定されていない場合のデフォルト値は 2 です。セルのセル エクスプローラー値が空の場合、そのセルは空白とみなされます。 この属性は、"セルを含む" 属性と連携して機能します。デフォルトの動作を確認するには、"セルを含む" を参照してください。 | 0 | ||||||||
セルも含める
API v37 で使用できます。 | なし | この属性は、"suppress- Zeroes" 特性の指示に従って、抑制されていないすべての行に対するセル レベルでの抑制を管理します。これを指定することで、出力にゼロや空白のセルが含まれるかどうかを制御します。有効な値は、0 (すべて含める - すべてのセルを表示)、1 (データとゼロを含める - 空白のセルを除外)、2 (データのみを含める - ゼロと空白のセルを除外) です。 デフォルトの動作: この属性が指定されていない場合、デフォルトの動作は "suppress- Zeroes" 特性によって決定されます。 さまざまな "suppress- Zeroes" 特性値に対する動作:
| 0 | ||||||||
show-cell-notes | なし | この属性が指定された場合、セル メモが表示または非表示になります。0= セル メモを表示しない (デフォルト)、1= セル メモを表示 | 1 | ||||||||
ロールアップしない | なし | この特性が指定されると、合計の行と列が表示または非表示になります。合計の行と列は、レポートに子が表示されている親にのみ表示されません。有効な値は 0 (合計を表示しない) または 1 (合計を表示しない) です。デフォルト値は 0 です。 | 1 | ||||||||
含める要素コード | なし | この特性が指定されると、"計算" (小計、差分、計算) 要素のコードが追加または非表示になります。有効な値は、0 (計算要素の出力にコードを追加しない) または 1 (計算要素の出力にコードを追加) です。デフォルト値は 0 です。 | 1 | ||||||||
エレメントの内容 | |||||||||||
詳細についてはリクエスト フォーマットを参照してください。 | |||||||||||
回答フォーマット
応答の XML スキーマは 、 customReportValues REST 仕様にあります。
<?xml version="1.0" encoding="utf-8"?> <response success="true"> <messages> <!-- Dimension value id 13 is invalid. Rows with value id 13 has been removed from the report. --> <message type="WARNING" key="invalid-dim-attr-id" values="199,13">Invalid value Id 199 for dimension/attribute type id 13 </message> </messages> <!-- Global filters. Although the request did not supply any filters, defaults are used when dimension types are not specified. Reporting against version with id 2 which is the current version. Level with id 1 is the top most level this user has access to. --> <filters> <coords> <coord type="ver" rollup="1"> <el id="2" /> </coord> <coord type="lvl" rollup="1"> <el id="1" /> </coord> </coords> </filters> <!-- Only two time columns Dec-2014 and Jan-2015 have data, all other columns have been removed --> <cols> <col id="1"> <coords> <coord type="time"> <el id="179001" /> </coord> </coords> </col> <col id="2"> <coords> <coord type="time"> <el id="180001" /> </coord> </coords> </col> <col id="3"> <coords> <coord code="Subtotal" type="subtotal" /> </coords> </col> </cols> <rows> <row> <!-- Row coordinates are account with id 51 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="51" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.345" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="2.345" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="4.69" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <!-- Row coordinates are account with id 53 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="53" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="7.44" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="12.78" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <coords> <coord code="Difference" type="diff" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.995" col="1" /> <cell value="5.095" col="2" /> <cell value="8.09" col="3" /> </row> <row> <coords> <coord type="calc" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <cell value="7.44" col="2" /> <cell value="12.78" col="3" /> </row> </rows> </report> </output> </response>
回答エレメント | |||
タグ名 | 回答 | ||
要素の特性 | |||
特性名 | 必須？ | 値 | 例 |
成功 | あり | 真偽のいずれか。API 呼び出しが成功したかどうかを示します。呼び出しが成功した場合でも、応答に警告メッセージが含まれる場合があります。 | true |
廃止 | なし | レスポンス タグに存在し、true に設定されている場合、この属性は呼び出しているメソッドまたは API のバージョンが廃止されており、正式に廃止されたことを示します。現時点では機能し続けていますが、まもなく機能が停止する可能性があります。通常、この属性は存在しません。 | false |
エレメントの内容 | |||
単一の任意のメッセージ要素と、厳密に 1 つの必須の出力要素。 | |||
メッセージ要素 | |
タグ名 | メッセージ |
説明 | 1 つ以上のメッセージ要素のコンテナです。 |
要素の特性 | |
(なし) | |
エレメントの内容 | |
1 つ以上のメッセージ要素 | |
メッセージ要素 | |||
タグ名 | メッセージ | ||
説明 | システムから呼び出し元に送り返されるメッセージを表します。メッセージは、リクエストが成功しない場合のエラー メッセージ、リクエストが成功した場合の警告メッセージ、成功した場合の確認メッセージに使用されます。 | ||
要素の特性 | |||
特性名 | 必須 ？ | 値 | 例 |
type | あり | タイプはメッセージのタイプを識別する方法です。異なるタイプは、INFO、 WARNING、ERROR です。"ERROR" タイプは、このリクエストが処理されなかったことを示します。 | 警告 |
キー | あり | キーは特定のメッセージやメッセージのタイプを識別するための手段で、クライアント プログラムにおけるエラー ログ記録と復旧に役立ちます。メッセージの言語が変わってもキーはリクエストのロケールの中で変更されません。また、単語の調整や用語の変更によってキーが将来変更される可能性も低いです。 | error-invalid-time-span-start |
値 | なし | 指定された値は、メッセージ テキストで使用される変数を表します。 | 199,12 |
エレメントの内容 | |||
メッセージのテキスト。このテキストは、リクエストで指定されたロケールの言語になります (そのロケールがサポートされている場合)。テキストには、処理された行数や、エラーの原因となった特定の列や値などの可変情報を含めることもできます。 | |||