Live data i HTML-sider i SharePoint

En HTML-side i SharePoint kører i en sandkasse, hvor fetch, XMLHttpRequest og alle andre netværkskald er blokeret (Microsoft). Alligevel kan siden vise data fra en liste, en Excel-fil eller en CSV-fil, og de er friske, hver gang siden åbnes (Microsoft). Det sker, fordi siden ikke selv henter noget. Den beder SharePoint om det.

Opskriften står i tenantens vejledning på https://<tenant>.sharepoint.com/_html, som kan læses uden login, og i en maskinlæsbar udgave, llms.txt (Microsoft). Den samme beskrivelse ligger i Microsofts repo SharePoint/sharepoint-html (GitHub).

Manifestet#

Siden erklærer sine kilder i en JSON-blok:

1<script type="application/json" class="ka-livedata-manifest">
2[{ "kind": "list",
3   "spItemUrl": "list:https://contoso.sharepoint.com/sites/Team/<liste-id>",
4   "webUrl": "https://contoso.sharepoint.com/sites/Team",
5   "listId": "<liste-id>",
6   "select": ["Title", "Status", "Ansvarlig"],
7   "label": "Opgaver" }]
8</script>

Når siden åbnes, henter SharePoint hver kilde med den besøgendes rettigheder og lægger resultatet i variablen window.__LD_RESULTS__, før sidens egne script kører (Microsoft). Der må være flere blokke; SharePoint samler dem (Microsoft).

Lister#

For en liste er kind, spItemUrl, webUrl og listId påkrævet. spItemUrl hentes aldrig; den er bare nøglen i resultatet og skal have formen list:{webUrl}/{listId}. Valgfrit er listServerRelativeUrl, viewId til en bestemt visnings kolonner, select med interne kolonnenavne og top som et hint om antal rækker (Microsoft).

Der er ingen filterparameter. Sidens script filtrerer og sorterer de rækker, den har fået.

Listens id og de interne navne findes, logget ind, med to REST-kald, som vejledningen selv angiver (Microsoft):

{webUrl}/_api/web/lists/getbytitle('Opgaver')?$select=Id
{webUrl}/_api/web/lists/getbytitle('Opgaver')/fields?$select=InternalName,Title,TypeAsString&$filter=Hidden eq false

Brug altid det interne navn. En kolonne, der hedder “By”, kan internt hedde noget helt andet, hvis den er omdøbt (Microsoft).

Brug også select. Uden den sender SharePoint alle listens kolonner til browseren. Denis Molodtsov fik 85 kolonner for en liste med et dusin egne, og en lønkolonne lå i data bag en side, der kun viste tre felter (spdenis.com).

Excel og CSV#

En fil angives med sit driveId og itemId og et filnavn med endelse (Microsoft):

1<script type="application/json" class="ka-livedata-manifest">
2[{ "spItemUrl": "https://contoso.sharepoint.com/_api/v2.0/drives/<drive-id>/items/<item-id>", "fileName": "budget.xlsx" }]
3</script>

SharePoint læser kun de to id’er og ignorerer værtsnavnet, så et manifest ikke kan pege på en anden tenant. Filnavnet bestemmer, hvordan filen læses; uden det kommer en Excel-fil som ulæselige bytes (Microsoft). En fil i en undermappe virker (spdenis.com).

Det, siden får#

Hver kilde har en post i window.__LD_RESULTS__ med format, content og ved fejl error og errorCode (Microsoft):

• En liste kommer som format: "rows": en JSON-streng med headers (interne navne) og rows.
• En Excel-fil kommer som xlsx-sheets: tekst med hvert ark i en <sheet name="...">-blok og CSV indeni.
• En CSV-fil kommer som rå tekst.

1var results = window.__LD_RESULTS__ || {};
2var entry = results[Object.keys(results)[0]];
3if (!entry) { /* ikke åbnet i SharePoint */ }
4else if (entry.error) { /* vis fejlen */ }
5else { var data = JSON.parse(entry.content); /* data.headers, data.rows */ }

Manglende adgang kommer nogle gange som not-found (Microsoft). Data skal sættes ind med textContent, aldrig innerHTML (Microsoft).

Opslag, personer og flervalg#

SharePoint gengiver listen med samme motor som Lists og gør hver kolonne til en tekst til visning (Microsoft). Et beløb kommer som "$115,000.00", ikke som et tal (spdenis.com). Et opslag kommer derfor efter alt at dømme som den viste værdi uden id, og et felt med flere værdier som én tekst. Hvordan værdierne adskilles, står der ikke. Skal siden bruge id’erne, kan man tilføje ID som ekstra felt på opslagskolonnen eller hente kildelisten som en kilde mere.

Opdatering#

Data hentes, hver gang siden åbnes, og uden om browserens cache. Siden kan bede om nye data:

1parent.postMessage({ type: 'ka-html-viewer-refresh' }, '*');

SharePoint accepterer højst én opdatering hvert 5. sekund, henter igen og genindlæser hele siden. Der kommer ingen besked om, at data er ændret (Microsoft). Mens siden redigeres, er der ingen live data (spdenis.com).

Grænser#

• Højst 32 kilder pr. side. Er der flere, får siden ingen data fra nogen af dem (Microsoft), og der vises ingen fejl (spdenis.com).
• Højst 50 MiB pr. datakilde, altså pr. Excel- eller CSV-fil i manifestet. En fil, der er større, eller hvor størrelsen ikke oplyses, afvises med fetch-failed (Microsoft). Det er en anden grænse end sidens egen: selve HTML-filen må højst fylde 10 MiB (Microsoft). I en test blev filer på 53 og 63 MB skåret ved 5 MB med en advarsel om en følsomhedsmærkat, filerne ikke havde (spdenis.com).
• Højst 100.000 rækker pr. liste. Resten skæres fra med en advarsel (Microsoft).

Siden kan ikke skrive#

Al trafik ud af siden er blokeret, og manifestet er den eneste vej ind (Microsoft). En formular kan ikke sende, og en knap kan ikke rette et element (spdenis.com). Skal brugerne rette data, må siden linke til listens egen formular, til Forms eller til en Power App.

Faldgruber#

• “Live” eller kopi. Copilot laver ikke altid en side, der læser listen. “Build an HTML page from my answers” gav en kopi af data skrevet ind i filen, “Create a live HTML page” en side med manifest (spdenis.com). En kopi kan alle med adgang til siden se, uanset rettighederne på listen (n8d.at). Tjek, om filen har et manifest.
• Rettighederne følger brugeren, men skjuler intet. Data hentes som den, der ser siden (Microsoft). Uden select ligger alle kolonner i browseren, også dem siden ikke viser.
• Ikke rigtigt live. Siden får et øjebliksbillede ved åbning. Ændres listen bagefter, vises det først ved næste opdatering (spdenis.com).
• Biblioteker med mapper. En side, der lister et biblioteks filer, ser kun roden (spdenis.com).