customReportValues
Aktualisiert in API v37.
Kategorie | Datenabruf |
Beschreibung | Gibt einen Datensatz für die angeforderten Berichtskriterien in der angeforderten Instanz zurück. |
Zum Aufrufen sind Berechtigungen erforderlich | Keine (dem Benutzer muss ein Berechtigungssatz zugewiesen sein) |
Auf Anforderung erforderliche Parameter | Zugangsdaten, Bericht |
Für API-Version 15 und höher rufen Sie exportTime auf, um die korrekten Zeitelement-IDs abzurufen
Unter Referenz: customReportValues-Performance-Bedingungen erfahren Sie, wie Sie sicherstellen können, dass Ihre Anforderungen von den in 2023R2 für API v36 veröffentlichten Verbesserungen an Performance und Skalierbarkeit profitieren.
Die Anforderung dieser Methode enthält eine Spezifikation für einen Bericht, mit dem Daten durchsucht und Werte zurückgegeben werden können. Die API verwendet interne ID-Nummern als Eingaben. APIs für den Metadatenabruf können aufgerufen werden, um gültige IDs abzurufen. Die Ergebnisse werden durch Koordinaten und Werte dargestellt. Die Antwort gibt ggf. auch Warnungen und Fehlermeldungen zurück.
Diese API basiert auf den Matrixberichten. Die Anforderung erfordert, dass der Aufrufer Elemente auf einer X-Achse (Spalten), einer Y-Achse (Zeilen) und auf einer optionalen Filterachse angibt, die zum Filtern aller von der API abgerufenen Daten verwendet werden. Matrixberichte enthalten Achsen, die bestimmen, welche Daten im Bericht angezeigt werden. Jede Achse definiert eine Ecke des Berichts. Alle Matrixberichte haben drei Achsen:
- X-Achse (Obergrenze). Sie definiert die Gruppe von Spalten im Bericht.
- Y-Achse (linker Rand). Sie definiert die Gruppe von Zeilen in einem Bericht
- die Filterachse, eine globale Achse, die Eigenschaften definiert, die für alle Daten im Bericht gelten. Weitere Informationen finden Sie in den Beispielen für Filterachse.
Eine Achse kann in mehrere Segmente unterteilt werden. Ein Segment ist eine Möglichkeit, Gruppen von Dimensionen auf einer einzelnen Achse zu trennen. Die Filterachse kann nur ein Segment enthalten, die anderen beiden Achsen jedoch beliebig viele Segmente.
Jedes Segment kann eine unbegrenzte Anzahl von Stufen haben. Eine Stufe stellt eine einzelne logische Dimension dar, die beschreibt, welche Elemente dieser Dimension für die darunter liegenden Zeilen oder Spalten gelten. Ein Segment kann nur maximal eine Stufe pro logische Dimension enthalten.
Jede Stufe kann ein oder mehrere Elemente der Dimension der Stufe enthalten. (Alle Elemente in der Stufe müssen zu der Dimension gehören, die in der Stufe angegeben ist.) Ein Element ist in der Regel ein Element in der Dimension, z. B. ein bestimmtes Konto in der Kontodimension oder ein Geschäftsquartal in der Zeitdimension. Diese Elemente werden dann vom System verwendet, um die im Bericht gefundenen Daten auszuwählen und zu aggregieren.
Wenn ein Segment auf der X- oder Y-Achse mehrere Stufen enthält, werden die Elemente jeder Stufe mit allen Elementen aller anderen Stufen kombiniert, um daskartesische Produkt aller möglichen Kombinationen von Stufenelementen zu bilden. Jede Spalte oder Zeile stellt eine mögliche Kombination von Elementen dar, wobei ein Element aus jeder Stufe ausgewählt wird. Wenn beispielsweise ein Segment auf der x-Achse – die Spalten oben – eine Stufe mit fünf Elementen und eine zweite Stufe mit zwei Elementen enthält, führt das Segment zu zehn separaten Spalten, die alle möglichen Kombinationen der Elemente in darstellen den Stufen. Sie können eine Elementart nicht auf mehreren Achsen platzieren. Wenn Sie z. B. die Kontoelementart in Zeilen platzieren, können Sie anschließend keine Konten zu Spalten oder Filtern hinzufügen.
Eine Stufe kann sowohl einzelne Elemente als auch Rollup-Elemente enthalten. Rollup-Elemente führen ein zufälliges Rollup für alle unter ihnen angegebenen Elemente durch. Rollup-Elemente sind im Filter nicht zulässig.
Die Filterachse verhält sich sehr ähnlich wie die X- und Y-Achse, hat jedoch einen kleinen Unterschied: Da die Filterachse für alle Daten im Bericht gilt, kann ihre Stufe nicht zu mehreren Zeilen oder Spalten kombiniert werden. Stattdessen kombiniert die Filterachse alle Elemente jeder Stufe und aggregiert die Daten aus allen Elementen, als ob für diese Elemente ein Rollup zu einer einzigen Aggregation durchgeführt würde.
Siehe: Einfache Matrixberichte erstellen finden Sie weitere Informationen zu Segmenten, Achsen und Dimensionselementen.
Beispiele für Filterachse
Das folgende Beispiel zeigt alle möglichen Elemente für die Filterachse.
<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>
Anforderungsformat
Das XML-Schema für die Anforderung finden Sie hier: customReportValues REST Spezifikation.
<?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>
Jeder Aufruf dieses API-Aufrufs muss genau ein Element von jeder der aufgeführten Arten enthalten:
-Zugangsdaten
-Bericht
Element „Zugangsdaten“. | |||
Tag-Name | -Zugangsdaten | ||
Beschreibung | Alle API-Aufrufe müssen ein einzelnes Element mit den Zugangsdaten enthalten, um den Benutzer zu identifizieren, der die API aufruft. Der API-Aufruf wird dann als dieser Benutzer ausgeführt (jeder Audit-Trail oder jede Aktionshistorie im System zeigt, dass dieser Benutzer die Aktion ausgeführt hat). Daher muss der Benutzer über die erforderlichen Berechtigungen zum Ausführen der Aktion verfügen, damit der API-Aufruf ausgeführt werden kann erfolgreich ist. | ||
Attribute des Elements | |||
Name des Attributs | erforderlich? | Wert | Beispiel |
login | J | Der Anmeldename des Benutzers, der die API-Methode aufruft. Dieser Benutzer muss über die erforderlichen Berechtigungen zum Aufrufen der Methode verfügen | sampleuser@company.com |
Kennwort | J | Das Kennwort des Benutzers, der die API-Methode aufruft. | my_password |
Gebietsschema | N | Geben Sie das Gebietsschema an, das verwendet werden soll, um eingehende Zahlen und Datumsangaben zu interpretieren und ausgehende Zahlen und Datumsangaben zu formatieren (mit dem entsprechenden Tausendertrennzeichen, den Monatsnamen und der Datumsformatierung). Das Gebietsschema wird auch verwendet, um die Sprache anzugeben, in der Systemmeldungen in der Antwort angezeigt werden sollen. Wenn nicht angegeben, wird en_US (amerikanisches Englisch) verwendet. | fr_FR |
instanceCode | N | Wenn der in den Zugangsdaten angegebene Benutzer Zugriff auf mehr als eine Instanz von hat, Adaptive Planning : Dieses Attribut kann verwendet werden, um anzugeben, dass der Benutzer auf eine andere Instanz als seine Standardinstanz zugreifen möchte. Wenn nicht angegeben, wird die Standardinstanz des Benutzers verwendet. Verwenden Sie die exportInstances-API, um die verfügbaren Instanzcodes zu ermitteln. | MYINSTANCE1 |
Inhalt des Elements | |||
(Keine) | |||
-Berichtselement | |||||||||||
Tag-Name | -Bericht | ||||||||||
Beschreibung | Gibt die Elemente an, aus denen der Bericht besteht. | ||||||||||
Attribute des Elements | |||||||||||
Name des Attributs | erforderlich? | Wert | Beispiel | ||||||||
Unterdrücken von Nullen
Aktualisiert in API v37. | N | Dieses Attribut steuert die Unterdrückung auf Zeilenebene. Durch die Angabe dieses wird gesteuert, ob die Ausgabe 0 oder leere Zeilen enthält oder nicht. Gültige Werte sind 0 (Nichts unterdrücken - Alle Zeilen anzeigen), 1 (Leere unterdrücken - Zeilen unterdrücken, die nur leere Zellen enthalten) und 2 (Leer und 0 unterdrücken - Zeilen unterdrücken, die nur leere oder Nullzellen enthalten). Wenn dieses Attribut nicht angegeben wird, ist der Standardwert 2. Eine Zelle wird als leer betrachtet, wenn der Wert im Zellen-Explorer für diese Zelle leer ist. Dieses Attribut funktioniert in Verbindung mit dem Attribut "cell-inclusions". Unter "Zelleneinschlüsse" sehen Sie das Standardverhalten. | 0 | ||||||||
Zelleinschlüsse
Verfügbar in API v37. | N | Dieses Attribut regelt die Unterdrückung auf Zellenebene für alle nicht unterdrückten Zeilen, wie durch das Attribut „suppress-0es“ vorgegeben. Durch die Angabe wird gesteuert, ob die Ausgabe null oder leere Zellen enthält oder nicht. Gültige Werte sind 0 (Alle einschließen - Alle Zellen anzeigen), 1 (Daten und 0 - Leere Zellen ausschließen) und 2 (Nur Daten einschließen - Nullen und leere Zellen ausschließen). Standardverhalten: Wenn dieses Attribut nicht angegeben ist, wird das Standardverhalten durch das Attribut „Nullen unterdrücken“ vorgegeben. Verhalten für unterschiedliche Werte des Attributs "Nullen unterdrücken":
| 0 | ||||||||
show-cell-notes | N | Wenn dieses Attribut angegeben ist, werden Zellnotizen entweder angezeigt oder ausgeblendet. 0 = Zellnotizen nicht anzeigen (Standard), 1 = Zellnotizen anzeigen | 1 | ||||||||
Unterdrückungs-Rollups | N | Wenn dieses Attribut angegeben ist, werden Rollup-Zeilen und -Spalten entweder angezeigt oder ausgeblendet. Rollup-Zeilen und -Spalten werden nur für die übergeordneten Elemente unterdrückt, deren untergeordnete Elemente im Bericht vorhanden sind. Gültige Werte sind 0 (Rollups nicht unterdrücken) oder 1 (Rollups unterdrücken). Der Standardwert ist 0. | 1 | ||||||||
include-element-code | N | Wenn angegeben, fügt dieses Attribut die Codes der Elemente „Berechnung“ (Zwischensumme, „Differenz“ und „Berechnung“) hinzu oder blendet sie aus. Gültige Werte sind 0 (Keine Codes zur Ausgabe für Berechnungselemente hinzufügen) oder 1 (Codes zur Ausgabe für Berechnungselemente hinzufügen). Der Standardwert ist 0. | 1 | ||||||||
Inhalt des Elements | |||||||||||
Weitere Details finden Sie im Anforderungsformat. | |||||||||||
Antwortformat
Das XML-Schema für die Antwort finden Sie unter customReportValues REST Specific.
<?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>
Antwortelement | |||
Tag-Name | -Antwort | ||
Attribute des Elements | |||
Name des Attributs | erforderlich? | Wert | Beispiel |
Erfolg haben | J | Entweder wahr oder falsch, was angibt, ob der API-Aufruf erfolgreich war oder nicht. Selbst erfolgreiche Aufrufe können in ihrer Antwort Warnmeldungen enthalten. | wahr |
obsolete | N | Wenn dieses Attribut im Antwort-Tag vorhanden ist und auf „true“ gesetzt ist, zeigt es an, dass die Version der Methode oder API, die aufgerufen wird, veraltet und offiziell veraltet ist. Auch wenn es zu diesem Zeitpunkt noch funktioniert, kann es sein, dass Sie in Kürze nicht mehr funktionieren. In der Regel ist dieses Attribut nicht vorhanden. | false |
Inhalt des Elements | |||
Ein einzelnes optionales Nachrichtenelement und genau ein erforderliches Ausgabeelement. | |||
Nachrichtenelement | |
Tag-Name | -Nachrichten |
Beschreibung | Container für ein oder mehrere Nachrichtenelemente. |
Attribute des Elements | |
(Keine) | |
Inhalt des Elements | |
Ein oder mehrere Nachrichtenelemente. | |
Nachrichtenelement | |||
Tag-Name | Nachricht | ||
Beschreibung | Stellt eine Nachricht dar, die vom System an den Aufrufer zurückgesendet wird. Nachrichten werden für Fehlermeldungen verwendet, wenn Anforderungen nicht erfolgreich sind, als Warnmeldungen, wenn Anforderungen erfolgreich sind, und als Bestätigungsmeldungen bei Erfolgreich. | ||
Attribute des Elements | |||
Name des Attributs | erforderlich ? | Wert | Beispiel |
type | J | Mit der Art kann die Art der Nachricht identifiziert werden. Die verschiedenen Arten sind "INFO", "Warning" und "ERROR". Die Art "ERROR" bedeutet, dass diese Anforderung nicht verarbeitet wurde. | WARNUNG |
-Schlüssel | J | Ein Schlüssel ist eine Möglichkeit, eine bestimmte Meldung oder eine bestimmte Meldungsart zu identifizieren. Dies ist für die automatische Fehlerprotokollierung und Wiederherstellung in Client-Programmen hilfreich. Schlüssel ändern sich nicht unter verschiedenen Gebietsschemas von Anforderungen, auch wenn sich die Sprache der Nachricht ändert. Es ist auch fehlgeschlagen, dass sich Schlüssel in Zukunft aufgrund von Wording-Anpassungen oder Änderungen der Terminologie ändern. | warning-invalid-time-spann-start |
-Werte | N | Wenn angegeben, stellen die Werte Variablen dar, die im Nachrichtentext verwendet werden. | 199,12 |
Inhalt des Elements | |||
Der Text der Nachricht. Dieser Text ist in der Sprache des in der Anforderung angegebenen Gebietsschemas (vorausgesetzt, das Gebietsschema wird unterstützt). Der Text kann auch variable Informationen enthalten, z. B. die Anzahl der verarbeiteten Zeilen oder die bestimmte Spalte oder den Wert, die einen Fehler verursacht haben. | |||
Ausgabeelement | |
Tag-Name | Ausgabe |
Beschreibung | |
Attribute des Elements | |
(Keine) | |
Inhalt des Elements | |
Weitere Details finden Sie in der XML-Antwort | |