customReportValues
Mis à jour dans l'API v37.
Catégorie | Extraction de données |
Description | Renvoie un ensemble de données pour les critères du rapport demandé dans l’instance demandée. |
Autorisations obligatoires pour pouvoir être appelées | Aucun (l’utilisateur doit avoir un ensemble d’autorisations affecté) |
Paramètres requis sur demande | Données d'identification, rapport |
Pour la version 15 de l’API et une version plus récente, appelez exportTime pour récupérer les bons identifiants des éléments de temps
Voir Référence : conditions de performance customReportValues pour savoir comment vous assurer que vos demandes tirent parti des améliorations en matière de performance et d’extenabilité publiées dans 2023R2 pour l’API v36.
La demande de cette méthode contient une spécification pour un rapport qui peut être utilisé pour rechercher des données et renvoyer des valeurs. L’API utilise les numéros d’identifiant interne comme données entrantes. Les API de récupération de métadonnées peuvent être appelées pour obtenir des identifiants valides. Les résultats sont représentés par des coordonnées et des valeurs. La réponse renvoie également des avertissements et des messages d’erreur, le cas échéant.
Cette API est fondée sur les subordonnés d’organisations matricielles. La demande exige que l’appelant précise des éléments sur un axe X (colonnes), un axe Y (rangées) et sur un axe de filtre facultatif utilisé pour filtrer toutes les données récupérées par l’API. Les rapports matriciels contiennent des axes qui déterminent les données affichées dans le rapport. Chaque axe définit un bord du rapport. Tous les rapports matriciels comportent trois axes :
- l’axe X (le bord supérieur). Il définit l’ensemble des colonnes du rapport.
- l’axe Y (le bord gauche). Il définit l’ensemble des rangées d’un rapport
- l’axe de filtre, un axe global qui définit les propriétés qui s’appliquent à toutes les données du rapport. Voir les exemples d’axe de filtre pour plus d’informations.
Un axe peut être divisé en plusieurs segments. Le segment est un moyen de séparer des ensembles de dimensions sur un seul axe. L’axe de filtre ne peut avoir qu’un seul segment, mais les deux autres axes peuvent avoir autant de segments que vous le souhaitez.
Chaque segment peut avoir un nombre illimité de paliers. Un palier représente une dimension logique unique utilisée pour décrire les éléments de cette dimension qui s’appliquent aux rangées ou aux colonnes sous elle. Un segment ne peut contenir qu’un palier au plus par dimension logique.
Chaque palier peut contenir un ou plusieurs éléments de la dimension du palier. (Tous les éléments du palier doivent appartenir à la dimension indiquée dans le palier.) Un élément est généralement un élément de la dimension, tel qu’un compte particulier dans la dimension de compte, ou un trimestre comptable dans la dimension de temps. Ces éléments sont ensuite utilisés par le système pour sélectionner et agréger les données trouvées dans le rapport.
Lorsqu’un segment de l’axe X ou Y contient plusieurs paliers, les éléments de chaque palier sont combinés avec tous les éléments de tous les autres paliers pour créer le produit cartésien de toutes les combinaisons possibles d’éléments de palier. Chaque colonne ou rangée représente une combinaison possible d’éléments, en sélectionnant un élément de chaque palier. Par exemple, si un segment sur l’axe X (les colonnes du haut) contient un palier à cinq éléments et un deuxième palier à deux éléments, le segment produira dix colonnes distinctes, représentant toutes les combinaisons possibles des éléments dans les paliers. Vous ne pouvez pas placer un type d'élément sur plusieurs axes. Par exemple, si vous placez le type d’élément de compte sur les lignes, vous ne pouvez pas ajouter de comptes sur les colonnes ou les filtres.
Un palier peut avoir des éléments individuels ou des éléments d’agrégat. Les éléments d'agrégat regroupent de manière arbitraire tous les éléments qui y sont précisés. Les éléments d'agrégat ne sont pas autorisés dans le filtre.
L’axe de filtre se comporte de manière très similaire aux axes X et Y, mais il présente une petite différence : comme l’axe de filtre s’applique à toutes les données du rapport, il ne peut pas combiner ses paliers pour créer plusieurs rangées ou colonnes. Au lieu de cela, l’axe de filtre combine tous les éléments de chaque palier, regroupant les données de tous les éléments comme si ces éléments étaient regroupés dans un seul regroupement.
Voir : Créer des rapports matriciels de base pour plus d’informations sur les segments, les axes et les éléments dimensionnels.
Exemples d'axes de filtre
L'exemple ci-dessous montre tous les éléments possibles pour l'axe de filtre.
<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>
Format de demande
Le schéma XML pour la demande peut être trouvé ici : customReportValeurs REST Specification.
<?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>
Chaque invocation de cet appel d’API doit contenir exactement un élément de chacun des types répertoriés :
données d'identification
rapport
élément de données d'identification | |||
Nom du marqueur | données d'identification | ||
Description | Tous les appels d’API doivent contenir un élément d’identification unique pour identifier l’utilisateur qui invoque l’API. L’appel d’API est alors effectué en tant que cet utilisateur (toute piste d’audit ou tout historique des actions dans le système indiquera que cet utilisateur a effectué l’action). Par conséquent, l’utilisateur doit disposer des autorisations requises pour effectuer l’action afin que l’appel d’API puisse être exécuté réussir. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
login | Y | Le nom de connexion de l’utilisateur qui invoque la méthode API. Cet utilisateur doit disposer des autorisations requises pour appeler la méthode | sampleuser@company.com |
mot de passe | Y | Le mot de passe de l’utilisateur qui invoque la méthode API. | my_password |
locale | N | Indiquez les paramètres régionaux à utiliser pour interpréter les numéros et les dates entrants et pour mettre en forme les numéros et les dates sortants (à l’aide du séparateur des milliers, des noms de mois et du format de date appropriés). Les paramètres régionaux sont également utilisés pour préciser la langue dans laquelle tous les messages de système de la réponse doivent être affichés. Si cette valeur n’est pas précisée, la valeur en_US (rubrique en anglais américain) est utilisée. | fr_FR |
instanceCode | N | Si l’utilisateur indiqué dans les données d’identification a accès à plusieurs instances de Adaptive Planning , cet attribut peut être utilisé pour préciser que l’utilisateur a l’intention d’accéder à une instance autre que celle par défaut. Si elle n’est pas précisée, l’instance par défaut de l’utilisateur sera utilisée. Pour déterminer les codes d’instances disponibles, utilisez l’API exportInstances. | MYINSTANCE1 |
Contenu de l'élément | |||
(aucun) | |||
élément de rapport | |||||||||||
Nom du marqueur | rapport | ||||||||||
Description | Indique les éléments qui composent le rapport. | ||||||||||
Attributs de l'élément | |||||||||||
Nom de l’attribut | Obligatoire? | Valeur | Exemple | ||||||||
suppress-zeroes
Mis à jour dans l'API v37. | N | Cet attribut régit la suppression au niveau de la rangée. Préciser cette option contrôlera si la sortie contient ou non des rangées nulles ou en blanc. Les valeurs valides sont 0 (supprimer rien - afficher toutes les rangées), 1 (supprimer en blanc - supprimer les rangées qui contiennent uniquement des cellules en blanc) et 2 (supprimer en blanc et zéro - supprimer les rangées contenant uniquement des cellules en blanc ou des cellules nulles). Si cet attribut n’est pas indiqué, la valeur par défaut est 2. Une cellule est considérée comme vide si la valeur de l’explorateur de cellules pour cette cellule est vide. Cet attribut fonctionne en conjonction avec l'attribut "cell-inclusions". Voir "cell-inclusions" pour vérifier le comportement par défaut. | 0 | ||||||||
cell-inclusions
Disponible dans API v37. | N | Cet attribut régit la suppression au niveau de la cellule pour toutes les rangées non supprimées, comme le dicte l'attribut "suppress-zeroes". Préciser cette option contrôlera si la sortie contient des cellules nulles ou vides. Les valeurs valides sont 0 (Inclure tout - afficher toutes les cellules), 1 (Inclure les données et les zéros - Exclure les cellules en blanc) et 2 (Inclure les données uniquement - Exclure les zéros et les cellules en blanc). Comportement par défaut : si cet attribut n'est pas indiqué, le comportement par défaut est dicté par l'attribut "suppress-zeroes". Comportement pour différentes valeurs d'attribut "suppress-zeroes" :
| 0 | ||||||||
show-cell-notes | N | Lorsqu’il est attribué, cet attribut affiche ou masque les notes des cellules. 0 = ne pas afficher les notes de cellule (par défaut), 1 = afficher les notes de cellule | 1 | ||||||||
supprime des agrégats | N | Lorsqu’il est fourni, cet attribut affiche ou masque les rangées et les colonnes d’agrégat. Les lignes et les colonnes d'agrégat sont supprimées uniquement pour les parents dont les enfants sont présents dans le rapport. Les valeurs valides sont 0 (Ne pas supprimer les agrégats) ou 1 (Supprimer les agrégats). La valeur par défaut est 0. | 1 | ||||||||
include-element-code | N | Lorsqu’il est attribué, cet attribut ajoute ou masque les codes des éléments Calculer (Total partiel, Différence et Calcul). Les valeurs valides sont 0 (Ne pas ajouter de codes à la sortie pour les éléments de calcul) ou 1 (Ajouter des codes à la sortie pour les éléments de calcul). La valeur par défaut est 0. | 1 | ||||||||
Contenu de l'élément | |||||||||||
Reportez-vous au format de demande pour plus de détails. | |||||||||||
Format de réponse
Le schéma XML pour la réponse se trouve dans customReportValises REST Specification.
<?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>
élément de réponse | |||
Nom du marqueur | réponse | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire? | Valeur | Exemple |
réussite | Y | Vrai ou faux, indiquant si l’appel d’API a réussi ou non. Même les appels réussis peuvent contenir des messages d’avertissement dans leur réponse. | true |
obsolète | N | S’il est présent dans le marqueur de réponse et défini à Vrai, cet attribut indique que la version de la méthode ou de l’API qui est appelée est obsolète et est officiellement dépréciée. Bien qu’elle continue de fonctionner pour le moment, elle pourrait cesser de fonctionner sous peu. En général, cet attribut n’est pas présent. | false |
Contenu de l'élément | |||
Un seul élément de message facultatif et un seul élément de sortie obligatoire. | |||
élément de message | |
Nom du marqueur | messages |
Description | Conteneur pour un ou plusieurs éléments de message. |
Attributs de l'élément | |
(aucun) | |
Contenu de l'élément | |
Un ou plusieurs éléments de message. | |
élément de message | |||
Nom du marqueur | message | ||
Description | Représente un message renvoyé par le système à l’appelant. Les messages sont utilisés pour envoyer des messages d’erreur lorsque les demandes échouent, pour envoyer des messages d’avertissement lorsque les demandes réussissent et pour les messages de confirmation lorsque les demandes réussissent. | ||
Attributs de l'élément | |||
Nom de l’attribut | Obligatoire | Valeur | Exemple |
type | Y | Le type est un moyen de désigner le type de message. Les différents types sont INFO, AVERTISSEMENT et ERREUR. Le type "ERROR" signifie que cette demande n'a pas été traitée. | AVERTISSEMENT |
clé | Y | Une clé est un moyen de repérer un message ou un type de message particulier, utile aux fins de journalisation automatique des erreurs et de récupération dans les programmes clients. Les clés ne changent pas selon les paramètres régionaux des demandes, même lorsque la langue du message change. Il est également improbable que les clés changent à l’avenir en raison d’ajustements de formulation ou de changements de terminologie. | Avertissement - Non valide - Intervalle de temps |
valeurs | N | Lorsqu’elles sont données, les valeurs représentent les variables utilisées dans le texte du message. | 199,12 |
Contenu de l'élément | |||
Le texte du message. Ce texte est dans la langue des paramètres régionaux indiqués dans la demande (en supposant que les paramètres régionaux sont pris en charge). Le texte peut également contenir des renseignements variables, tels que le nombre de rangées traitées, ou la colonne ou la valeur particulière qui a causé une erreur. | |||
élément de sortie | |
Nom du marqueur | sortie |
Description | |
Attributs de l'élément | |
(aucun) | |
Contenu de l'élément | |
Consultez la version XML de la réponse pour avoir plus de détails | |