Tabelgegevens opvragen voor rapportage

Doel

De gegevens van een tabel uit één omgeving lezen via de alleen-lezen rapportagegegevensbron, zodat een externe rapportage- of analyse-integratie de tabellen kan opsommen die ze mag lezen, de kolommen van een tabel kan opvragen, pagina's met rijen kan ophalen en een opgeslagen query kan uitvoeren, zonder enige schrijftoegang.

Vereisten

• Een registratie van een externe toepassing met de scope reporting.read (of modelapps.read, die ook rapportagelezingen toestaat) en een rol die de benodigde tabellen mag lezen. Zie Een externe toepassing registreren.
• Een toegangstoken voor die registratie, aangevraagd met de scope bij naam.
• De id van de omgeving waarvan u de gegevens wilt lezen.

Het rapportageoppervlak

Alle bewerkingen gelden voor één omgeving en zijn alleen-lezen. Twee dingen bepalen wat u krijgt: de scope opent het oppervlak, en de rol van de toepassing bepaalt welke tabellen en welke rijen, precies zoals voor een persoon in een app. Een token met de scope en zonder rol bereikt geen enkele rij.

Bewerking	Verzoek	Resultaat
Tabellen opsommen	GET /environments/{environmentId}/reporting/entities	De tabellen die uw rol mag lezen (logische naam, weergavenaam, meervoudsnaam).
De kolommen van een tabel beschrijven	GET /environments/{environmentId}/reporting/entities/{entity}/schema	Elke kolom: logische naam, weergavenaam, gegevenstype, of het het primaire veld is, en de doeltabel van een zoekveld.
Een gegevensset lezen	POST /environments/{environmentId}/reporting/entities/{entity}/dataset	columns en rows, plus totalCount, pageNumber en pageSize.
Een opgeslagen query uitvoeren	POST /environments/{environmentId}/saved-queries/{logicalName}/run	De records of groepen van de opgeslagen query.

Een gegevenssetverzoek

De body is een query: select (de kolommen die u wilt), filter (een verbinding en voorwaarden, elk met veld, operator en waarde), order (velden, oplopend of aflopend) en page (number en 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 }
}

Met select beschrijft columns precies die kolommen, in die volgorde. Een keuzekolom komt terug als getal en daarnaast het label onder <kolom>__text. Uit totalCount leest u hoeveel pagina's er zijn.

Een opgeslagen query

Een query die een maker heeft ontworpen en opgeslagen, voert u uit op logische naam. De body is optioneel en kan de query alleen verengen: een extra filter komt bij het opgeslagen filter, vervangt het nooit, en page kiest een pagina. Een gegroepeerde query antwoordt met haar groepen en hun metingen, zodat een integratie om totalen kan vragen in plaats van zelf rijen op te tellen.

Wat er achter de schermen gebeurt

De rapportagegegevensbron kent geen maken, wijzigen of verwijderen. Elk verzoek controleert eerst de scope van het token en leest dan via dezelfde weg als de schermen van het platform, zodat de rechten van de rol en hun beleid de rijen bepalen. Alleen de omgeving uit de route wordt gelezen.

Problemen oplossen

• 403 met modelapps.reporting.forbidden. Het token draagt geen reporting.read of modelapps.read. Vraag de scope bij naam aan wanneer u het token aanvraagt: een token zonder scope draagt er geen.
• 403 met modelapps.record.forbidden. De scope is er, maar de rol van de toepassing mag die tabel niet lezen. Geef de rol in deze omgeving Lezen erop.
• Een tabel ontbreekt in de lijst. De rol mag haar niet lezen, of ze bestaat niet in deze omgeving.
• 400 voor een onbekend veld. Een veld in select, filter of order hoort niet bij de tabel. Gebruik een veld uit het schema van de tabel.

Gerelateerde scenario's

• Een externe toepassing registreren.
• Een rapport aan een tabel koppelen (maker).