Tabellendaten für Berichte abfragen

Ziel

Die Daten einer Tabelle aus einer Umgebung über die schreibgeschützte Berichtsdatenquelle lesen, damit eine externe Berichts- oder Analyseintegration die Tabellen auflisten kann, die sie lesen darf, die Spalten einer Tabelle ermitteln, Seiten von Zeilen abrufen und eine gespeicherte Abfrage ausführen kann, ganz ohne Schreibzugriff.

Voraussetzungen

• Eine Registrierung einer externen Anwendung mit dem Scope reporting.read (oder modelapps.read, das Berichtslesezugriffe ebenfalls gewährt) und einer Rolle, die die benötigten Tabellen lesen darf. Siehe Externe Anwendung registrieren.
• Ein Zugriffstoken für diese Registrierung, bei dessen Anforderung der Scope namentlich genannt wurde.
• Die Kennung der Umgebung, deren Daten Sie lesen möchten.

Die Berichtsschnittstelle

Alle Vorgänge betreffen genau eine Umgebung und sind schreibgeschützt. Zwei Dinge entscheiden, was Sie erhalten: Der Scope öffnet die Schnittstelle überhaupt, und die Rolle der Anwendung entscheidet, welche Tabellen und welche Zeilen, genau wie für eine Person in einer App. Ein Token mit dem Scope und ohne Rolle erreicht keine Zeilen.

Vorgang	Anfrage	Ergebnis
Tabellen auflisten	GET /environments/{environmentId}/reporting/entities	Die Tabellen, die Ihre Rolle lesen darf (logischer Name, Anzeigename, Pluralname).
Spalten einer Tabelle beschreiben	GET /environments/{environmentId}/reporting/entities/{entity}/schema	Jede Spalte: logischer Name, Anzeigename, Datentyp, ob sie das Primärfeld ist, und die Zieltabelle einer Suche.
Einen Datensatz lesen	POST /environments/{environmentId}/reporting/entities/{entity}/dataset	columns und rows sowie totalCount, pageNumber und pageSize.
Eine gespeicherte Abfrage ausführen	POST /environments/{environmentId}/saved-queries/{logicalName}/run	Die Datensätze oder Gruppen der gespeicherten Abfrage.

Eine Datensatzanfrage

Der Rumpf ist eine Abfrage: select (die gewünschten Spalten), filter (ein Verknüpfer und Bedingungen, jede mit Feld, Operator und Wert), order (Felder, je auf- oder absteigend) und page (number und size):

{
  "select": ["nw_name", "nw_company"],
  "filter": { "connector": "And",
              "conditions": [{ "field": "nw_company", "operator": "Equals", "value": "Analytical Engines" }] },
  "order": [{ "field": "nw_name", "descending": false }],
  "page": { "number": 1, "size": 50 }
}

Mit select beschreibt columns genau diese Spalten in dieser Reihenfolge. Eine Auswahlspalte kommt als Zahl zurück und daneben ihre Beschriftung unter <Spalte>__text. Aus totalCount ergibt sich, wie viele Seiten es gibt.

Eine gespeicherte Abfrage

Eine Abfrage, die ein Maker entworfen und gespeichert hat, lässt sich über ihren logischen Namen ausführen. Der Rumpf ist optional und kann sie nur einschränken: Ein zusätzlicher filter kommt zum gespeicherten hinzu, ersetzt ihn nie, und page wählt eine Seite. Eine gruppierte Abfrage antwortet mit ihren Gruppen und deren Kennzahlen, sodass eine Integration Summen anfordern kann, statt Zeilen selbst zu addieren.

Was im Hintergrund passiert

Die Berichtsdatenquelle kennt kein Erstellen, Ändern oder Löschen. Jede Anfrage prüft zuerst den Scope des Tokens und liest dann über denselben Weg wie die Bildschirme der Plattform, sodass die Berechtigungen der Rolle und ihre Richtlinien über die Zeilen entscheiden. Gelesen wird nur die in der Route genannte Umgebung.

Fehlerbehebung

• 403 mit modelapps.reporting.forbidden. Das Token trägt weder reporting.read noch modelapps.read. Nennen Sie den Scope bei der Tokenanforderung namentlich: Ein Token, das ohne scope angefordert wurde, trägt keinen.
• 403 mit modelapps.record.forbidden. Der Scope ist vorhanden, aber die Rolle der Anwendung darf diese Tabelle nicht lesen. Gewähren Sie der Rolle in dieser Umgebung Lesen darauf.
• Eine Tabelle fehlt in der Liste. Die Rolle darf sie nicht lesen, oder es gibt sie in dieser Umgebung nicht.
• 400 wegen eines unbekannten Felds. Ein Feld in select, filter oder order gehört nicht zur Tabelle. Verwenden Sie ein Feld aus dem Schema der Tabelle.

Verwandte Szenarien

• Externe Anwendung registrieren.
• Einen Bericht an eine Tabelle binden (Maker).