Koble til Telescope

Du legger til to parametere, fire hjelpespørringer og seks tabeller i Power BI Desktop. Det tar rundt ti minutter, og alt du gjør er å kopiere og lime inn.

Menynavn

Menyer, knapper og innstillinger er oppgitt slik de heter i den engelske versjonen av Power BI.

1. Åpne Power Query

I Power BI Desktop velger du Home → Transform data. Power Query Editor åpnes. Alle stegene nedenfor gjøres der.

2. Legg til parameterne

Velg Home → Manage Parameters → New Parameter og legg til to parametere:

Navn	Type	Gjeldende verdi
TelescopeBaseUrl	Text	https://api.telescope.eco
TelescopeApiKey	Text	API-nøkkelen din, som starter med tel_

Basis-URL-en er en parameter slik at du kan peke rapporten mot staging, og slik at Power BI Service kan oppdatere den. Se hvorfor.

3. Legg til hjelpespørringene

For hver spørring nedenfor velger du Home → New Source → Blank Query, deretter Home → Advanced Editor. Erstatt alt med koden og velg Done. Gi så spørringen nytt navn (høyreklikk den i Queries-panelet → Rename) etter navnet i overskriften.

TelescopeGet

Henter én API-sti og returnerer JSON-dataene.

(path as text, optional query as nullable record) =>
    Json.Document(
        Web.Contents(
            TelescopeBaseUrl,
            [
                RelativePath = path,
                Query = if query = null then [] else query,
                Headers = [#"X-API-Key" = TelescopeApiKey, Accept = "application/json"]
            ]
        )
    )

TelescopeList

Henter alle sidene fra et listeendepunkt og returnerer alle resultatene.

(path as text, optional filters as nullable record) =>
let
    BaseQuery = if filters = null then [] else filters,
    GetPage = (cursor as nullable text) =>
        TelescopeGet(path, if cursor = null then BaseQuery else BaseQuery & [cursor = cursor]),
    // Only the cursor is read from `next`, so requests always go to TelescopeBaseUrl
    NextCursor = (page as record) =>
        if page[next] = null then null else Uri.Parts(page[next])[Query][cursor],
    Pages = List.Generate(
        () => GetPage(null),
        (page) => page <> null,
        (page) => let cursor = NextCursor(page) in
            if cursor = null then null else GetPage(cursor),
        (page) => page[results]
    )
in
    List.Combine(Pages)

TelescopePropertiesRaw

Laster inn alle eiendommene én gang. Tabellene nedenfor henter radene sine herfra.

let
    Source = TelescopeList("external/properties/")
in
    Source

Vil du bare laste inn noen av eiendommene, sender du filtre som en record, for eksempel TelescopeList("external/properties/", [hazard_relevant = "true"]).

TelescopeNested

Gjør én av de nøstede listene for hver eiendom om til rader med en property_id-kolonne.

(field as text, columns as list) as table =>
let
    Rows = List.Combine(
        List.Transform(
            TelescopePropertiesRaw,
            (property) => List.Transform(
                Record.Field(property, field),
                (item) => Record.SelectFields(
                    item & [property_id = property[id]],
                    columns,
                    MissingField.UseNull
                )
            )
        )
    )
in
    Table.FromRecords(Rows, columns)

Slå av innlasting for hjelpespørringene

Hjelpespørringene er ikke tabeller du vil ha i rapporten. Høyreklikk TelescopePropertiesRaw og fjern haken for Enable load. Funksjonene og parameterne lastes ikke inn uansett.

4. Legg til tabellene

Legg til hver av disse på samme måte: en tom spørring, koden i Advanced Editor, og så nytt navn.

Properties

let
    Columns = {
        "id", "internal_reference_id", "name", "value_estimate", "portfolio_id",
        "address", "postal_code", "postal_area", "country", "matrikkelnummer",
        "created_at", "updated_at"
    },
    Rows = List.Transform(
        TelescopePropertiesRaw,
        each Record.SelectFields(_, Columns, MissingField.UseNull)
    ),
    Properties = Table.FromRecords(Rows, Columns),
    Typed = Table.TransformColumnTypes(Properties, {
        {"id", type text}, {"internal_reference_id", type text}, {"name", type text},
        {"value_estimate", Int64.Type}, {"portfolio_id", type text},
        {"address", type text}, {"postal_code", type text}, {"postal_area", type text},
        {"country", type text}, {"matrikkelnummer", type text},
        {"created_at", type datetimezone}, {"updated_at", type datetimezone}
    })
in
    Typed

Hazards

let
    Source = TelescopeNested(
        "hazards",
        {"property_id", "name", "exposure", "relevant", "sensitivity", "vulnerability", "updated_at"}
    ),
    Typed = Table.TransformColumnTypes(Source, {
        {"property_id", type text}, {"name", type text}, {"exposure", type text},
        {"relevant", type logical}, {"sensitivity", type text},
        {"vulnerability", type text}, {"updated_at", type datetimezone}
    }),
    // Lets you sort exposure from lowest to highest instead of alphabetically
    WithOrder = Table.AddColumn(
        Typed,
        "exposure_order",
        each List.PositionOf(
            {"NOT_EXPOSED", "VERY_LOW", "LOW", "MEDIUM", "HIGH", "VERY_HIGH"},
            [exposure]
        ),
        Int64.Type
    )
in
    WithOrder

Biodiversity

let
    Source = TelescopeNested(
        "biodiversity",
        {"property_id", "name", "relevant", "proximity", "updated_at"}
    ),
    Typed = Table.TransformColumnTypes(Source, {
        {"property_id", type text}, {"name", type text}, {"relevant", type logical},
        {"proximity", type text}, {"updated_at", type datetimezone}
    })
in
    Typed

Buildings

let
    Source = TelescopeNested(
        "buildings",
        {
            "property_id", "id", "government_id", "name", "usage",
            "construction_year", "usage_area", "num_floors"
        }
    ),
    Typed = Table.TransformColumnTypes(Source, {
        {"property_id", type text}, {"id", type text}, {"government_id", type text},
        {"name", type text}, {"usage", type text}, {"construction_year", Int64.Type},
        {"usage_area", type number}, {"num_floors", Int64.Type}
    })
in
    Typed

EnergyCertificates

let
    Source = TelescopeNested(
        "energy_certificates",
        {
            "property_id", "id", "building_id", "label", "energy_use_by_m2",
            "issued_at", "expires_at"
        }
    ),
    Typed = Table.TransformColumnTypes(Source, {
        {"property_id", type text}, {"id", type text}, {"building_id", type text},
        {"label", type text}, {"energy_use_by_m2", type number},
        {"issued_at", type datetimezone}, {"expires_at", type datetimezone}
    })
in
    Typed

Portfolios

Mappelisten returnerer bare rotmapper, så denne spørringen går gjennom treet: den henter detaljene for hver mappe for å finne undermappene. Kolonnen path inneholder hele navnet, for eksempel Norway / Oslo / Office.

let
    Walk = (portfolio as record, parentPath as nullable text) as list =>
        let
            Detail = TelescopeGet("external/portfolios/" & portfolio[id] & "/"),
            Path = if parentPath = null then Detail[name] else parentPath & " / " & Detail[name],
            Row = [
                id = Detail[id],
                name = Detail[name],
                internal_reference_id = Detail[internal_reference_id],
                parent_id = Detail[parent_id],
                path = Path,
                updated_at = Detail[updated_at]
            ],
            Children = List.Transform(Detail[portfolios], (child) => @Walk(child, Path))
        in
            {Row} & List.Combine(Children),
    Roots = TelescopeList("external/portfolios/"),
    Rows = List.Combine(List.Transform(Roots, (root) => Walk(root, null))),
    Portfolios = Table.FromRecords(
        Rows,
        {"id", "name", "internal_reference_id", "parent_id", "path", "updated_at"}
    ),
    Typed = Table.TransformColumnTypes(Portfolios, {
        {"id", type text}, {"name", type text}, {"internal_reference_id", type text},
        {"parent_id", type text}, {"path", type text}, {"updated_at", type datetimezone}
    })
in
    Typed

Spørringen gjør én forespørsel per mappe. Med flere hundre mapper er dette den tregeste delen av en oppdatering.

5. Logg på

Første gang en spørring kjører, spør Power BI hvordan den skal koble til https://api.telescope.eco. Velg Anonymous og deretter Connect. API-nøkkelen sendes allerede i headeren X-API-Key, så Power BI skal ikke legge til egen pålogging.

Valgte du noe annet ved en feil, endrer du det under File → Options and settings → Data source settings: velg Telescope-URL-en, og så Edit Permissions → Edit → Anonymous.

6. Last inn dataene

Queries-panelet skal nå se slik ut:

Velg Home → Close & Apply. Power BI laster inn de seks tabellene. Fortsett med datamodellen.

Bruk staging

Sett TelescopeBaseUrl til https://api-staging.telescope.eco og TelescopeApiKey til en nøkkel fra staging. Nøkler fungerer bare i miljøet de ble opprettet i.