Anslut Power Apps till DirSys API via anpassad connector

Anslut Power Apps till DirSys API via anpassad connector

Så ansluter du Power Apps till DirSys REST API med en anpassad connector.

API DirSys Public API v1.0.0 · Connector OpenAPI 2.0 (Swagger) · Testad med Power Platform CLI (pac) 2.11.2

Om guiden

Guiden visar hur du gör data från DirSys tillgänglig i Power Apps genom att bygga en anpassad connector (custom connector) och sedan använda den i en canvas-app.

Som genomgående exempel används personuppgiftsbehandlingar i DirSys Integrity. Metoden är dock inte specifik för den resursen — samma tillvägagångssätt gäller för informationsbärare i DirSys Security och för övriga delar av API:et. Byt ut sökvägar och schemanamn så kan samma steg i huvudsak följas.

Kommandon och versionsberoende beteenden är verifierade med Power Platform CLI 2.11.2. Andra versioner kan bete sig något annorlunda; guiden markerar de ställen där versionsskillnader är kända.

Det här bygger guiden

En canvas-app som listar personuppgiftsbehandlingar med ansvarig personuppgiftsansvarig, skapandedatum och DPIA-status per rad. Data hämtas direkt från API:t när appen startas.

Personuppgiftsbehandlingar
Elektronisk kommunikation
DirSys
Skapad 2022-10-26  |  ingen DPIA
Kundkommunikation
DirSys
Skapad 2022-04-11  |  ingen DPIA
Kundregister
DirSys
Skapad 2022-11-16  |  ingen DPIA
Lokaltillträde
DirSys
Skapad 2022-10-26  |  ingen DPIA

Så fungerar kopplingen

Appen anropar aldrig DirSys API direkt. Anropet går genom den anpassade connectorn, och det är där connectorns policies körs.

Klient
Canvas-app
Galleri med Power Fx-formler
→
Mellanlager
Connectortjänsten
Hanterar anslutningen och kör connectorns policies
→
Backend
DirSys API
api.dirsys.app

Canvas-appen anropar DirSys API genom den anpassade connectorn. Power Platforms connectortjänst hanterar anslutningen och kör connectorns policies innan anropet skickas vidare. Policies är funktioner som modifierar anropet at runtime — de kan exempelvis sätta headers eller skriva om sökvägen. Merparten av anropet vidarebefordras oförändrat. I en delad app skjuts ett Power Automate-flöde in mellan appen och connectorn — se steg 7.

Förutsättningar

  • En Power Platform-miljö där du har behörighet att skapa anpassade connectorer.
  • Power Apps-licens med stöd för premium/custom connectors. En Power App som använder en anpassad connector klassificeras som en Premium-app. Kontrollera därför att de användare som ska köra appen har rätt Power Apps-licens. Ska connectorn dessutom användas i Power Automate-flöden utanför appens kontext tillkommer motsvarande krav på Power Automate-licens.
  • Power Platform CLI: winget install Microsoft.PowerAppsCLI. Kommandot heter pac.
  • En DirSys API-nyckel och API:ets OpenAPI-definition.

Steg 1 – Förbered OpenAPI-definitionen

Power Platforms anpassade connectorer kräver OpenAPI 2.0 (Swagger) vid import och accepterar inte OpenAPI 3.0. DirSys API publiceras som OpenAPI 3.0.1, så definitionen behöver konverteras.

De viktigaste strukturella skillnaderna är:

# OpenAPI 3.0.1                   # OpenAPI 2.0 (Swagger)
servers: [{ url: "https://…" }] host + basePath + schemes
components.schemas definitions
$ref: '#/components/schemas/X' $ref: '#/definitions/X'
content: { application/json: … } produces + schema

För de endpoints som används i det här exemplet är merparten av paths, parametrar och enklare scheman direkt överförbara. Mer avancerade OpenAPI 3-funktioner — exempelvis requestBody, vissa schemakonstruktioner och hur innehållstyper (content types) beskrivs — kan kräva ytterligare anpassning.

Steg 2 – Konfigurera autentisering

DirSys API använder Authorization: Bearer <nyckel>. Konfigurationen ligger i två filer som måste hålla ihop: nyckeln i connectionParameters måste heta exakt samma sak som nyckeln i securityDefinitions.

// apiDefinition.swagger.json
"securityDefinitions": {
"api_key": { "type": "apiKey", "in": "header", "name": "Authorization" }
},
"security": [{ "api_key": [] }]
// apiProperties.json
"connectionParameters": {
"api_key": { "type": "securestring", "uiDefinition": { … } }
}

Värdet skickas rakt av som headern. Vill du slippa be användaren skriva Bearer  själv lägger du på prefixet med en policy:

{
"templateId": "setheader",
"title": "Add Bearer prefix to Authorization header",
"parameters": {
"x-ms-apimTemplateParameter.name": "Authorization",
"x-ms-apimTemplateParameter.value": "Bearer @connectionParameters('api_key', '')",
"x-ms-apimTemplateParameter.existsAction": "override",
"x-ms-apimTemplate-policySection": "Request",
"x-ms-apimTemplate-operationName": []
}
}

Tom operationName-array betyder "alla operationer".

Steg 3 – Skapa DirSys-connectorn

Logga in mot din miljö och skapa connectorn:

pac auth create
pac connector create \
--api-definition-file apiDefinition.swagger.json \
--api-properties-file apiProperties.json \
--icon-file icon.png

Svaret innehåller connectorns ID. Efterföljande ändringar distribueras med pac connector update --connector-id <guid> och samma filflaggor.

Notering om pac CLI 2.11.2

I Power Platform CLI 2.11.2 kan --settings-file orsaka problem vid den första deployen om connectorId ännu inte har ett giltigt GUID-värde. Ett alternativ är att ange API-definitionen och connector-egenskaperna direkt med --api-definition-file och --api-properties-file. Beteendet kan skilja sig mellan CLI-versioner; pac connector init kan generera en settings-fil om du vill använda den vägen.

Steg 4 – Testa connectorn

Verifiera att API:t, autentiseringen och connectorn fungerar innan Power Apps och Power Fx blandas in. Då vet du var ett eventuellt fel sitter.

  1. Skapa en connection till DirSys-connectorn.
  2. Ange API-nyckeln när du ombeds.
  3. Kör en operation, exempelvis ListPersonalDataProcesses.
  4. Verifiera HTTP 200.
  5. Verifiera att svaret innehåller .data med en array av poster — det är den nivån appen kommer att binda mot.
Om testfliken svarar 403

Connector-editorns inbyggda testflik körs i webbläsarkontext och omfattas inte av alla connector-policies. Det innebär att anropet går från den dator du sitter vid. Får du 403 Invalid CORS request behöver Origin-headern hanteras enligt avsnittet om Origin längre ned.

Alternativ verifiering: lägg operationen som ett steg i ett Power Automate-flöde och kör det. Flöden anropar på serversidan och påverkas inte av samma begränsning.

Steg 5 – Bygg canvas-appen

Skapa en tom canvas-app i surfplatteformat och lägg till connectorn under Lägg till data. Sätt sedan galleriets Items till operationen:

DirSys.ListPersonalDataProcesses(
{page:0; size:100; sort:"name"}
).data

.data på slutet plockar ut arrayen ur pagineringswrappern. Utan den binder galleriet mot wrapper-objektet, och fälten du kan välja blir page, size och totalElements i stället för postens egna fält — ett tydligt tecken på att den glömts.

Välj en gallerilayout utan bild när API:et inte returnerar bild-URL:er. Behåller du bildlayouten blir det kvar en bildkontroll vars formel inte kan utvärderas, och hela galleriet renderas tomt.

Hela appens logik består av fyra formler. Layouten är "Rubrik, underrubrik och brödtext":

KontrollEgenskapFormel
Gallery1 Items DirSys.ListPersonalDataProcesses({page:0; size:100; sort:"name"}).data
Title1 Text ThisItem.name
Subtitle1 Text Concat(ThisItem.controllers; name; ", ")
Body1 Text "Skapad " & Text(ThisItem.createdAt; DateTimeFormat.ShortDate)
& If(ThisItem.hasDpia; " | DPIA finns"; " | ingen DPIA")

Direkt bindning eller via flöde?

Formeln ovan binder galleriet direkt mot connectorn. Det är den enklaste formen, och den du vill ha när du bygger och testar. Ska appen sedan delas med andra användare visar steg 7 den uppsättning som rekommenderas — appen anropar då DirSys API via ett Power Automate-flöde, så att slutanvändarna aldrig behöver hantera API-nyckeln. Bygg klart här först; bytet i steg 7 rör bara galleriets Items.

Concat plattar ut en nästlad array till en sträng — här alla personuppgiftsansvariga för en behandling. DateTimeFormat.ShortDate är språkoberoende, till skillnad från formatsträngar som "yyyy-mm-dd". Formlerna är skrivna som de matas in i en svensk miljö; se separatorn under Felsökning.

Steg 6 – Testa och publicera

Designytan anropar API:et på riktigt — ser du data där fungerar kopplingen. Förhandsgranska med uppspelningsknappen (Play) och klicka Publicera när appen ska bli tillgänglig för andra.

Går något fel: öppna App-kontrolleraren och gå till fliken Körning. Den visar faktiska körningsfel med HTTP-statuskod. Fliken Formler visar statisk analys och kan ligga kvar på redan åtgärdade fel — utgå från Körning när de två säger emot varandra.

Steg 7 – Dela appen

När en Power App använder en anpassad connector direkt behöver varje användare normalt ha en egen connection till connectorn. Om DirSys API använder en gemensam integrationsnyckel är det därför lämpligare att låta appen anropa DirSys API via ett Power Automate-flöde.

Power App
↓
Power Automate-flöde
↓
Gemensam connection
↓
DirSys custom connector
↓
DirSys API

Detta ersätter den direkta bindningen från steg 5

Formeln i steg 5 binder galleriet direkt mot connectorn. Det är den enklaste formen och räcker för att komma igång, men den förutsätter att varje användare har en egen connection. Ska appen delas byter du ut den mot ett anrop till flödet nedan — galleriets Items pekar då på flödets svar i stället för på DirSys.ListPersonalDataProcesses(…). Resten av appen är oförändrad.

Rekommenderad uppsättning

  1. Skapa en dedikerad DirSys integrationsnyckel för integrationen.
  2. Skapa en connection till DirSys-connectorn med integrationsnyckeln.
  3. Skapa ett Power Automate-flöde som använder denna connection.
  4. Låt Power Appen anropa flödet i stället för att anropa DirSys-connectorn direkt.
  5. Konfigurera flödet så att den befintliga connectionen används när appens användare kör flödet.
  6. Dela Power Appen och ge användarna rätt att köra det tillhörande flödet.

På detta sätt behöver slutanvändarna inte känna till eller själva ange DirSys API-nyckeln. API-nyckeln lagras i connectorns connection och används av Power Automate-flödet när anrop görs mot DirSys API.

Säkerhetsprincip

API-nycklar ska aldrig sparas i Power Fx-formler, appvariabler eller i appens källkod. De ska hanteras som säkra parametrar i connectorns connection.

En dedikerad integrationsnyckel bör användas för varje integration. Det gör det möjligt att begränsa behörigheter, rotera nyckeln och spärra integrationen utan att påverka andra API-klienter.

Eftersom flera Power App-användare kan använda samma integrationsnyckel representerar anropen till DirSys API integrationen snarare än den enskilda användaren. Om olika användargrupper behöver separeras i loggning eller behörighet bör separata integrationsnycklar och flöden användas.

Felsökning

Fyra fel där felmeddelandet inte pekade på den verkliga orsaken.

Power Fx byter separator med språkinställningen

I en svensk miljö är listseparatorn i Power Fx ;, inte ,. Samma formel som fungerar i en engelsk miljö ger här kryptiska fel om att "operator förväntades" eller om oväntade tecken.

// svensk miljö
DirSys.ListPersonalDataProcesses({page:0; size:100; sort:"name"}).data
// engelsk miljö
DirSys.ListPersonalDataProcesses({page:0, size:100, sort:"name"}).data

Det gäller bara vad du skriver. Packar du upp appens källkod med pac canvas unpack står det alltid , i YAML:en oavsett språk — en formel kopierad ur källkoden måste alltså översättas innan den klistras in i en svensk Studio.

Otypat svar ger tomt resultat utan felmeddelande

En endpoint vars svar deklarerats som {"type": "object"} utan properties ger Power Fx ingen typ att bygga på. Anropet lyckas, inget fel visas, och resultatet är blankt. Det ser ut som ett nätverksfel men är ett schemafel.

Lösning
Deklarera fälten i Swagger-definitionen. Saknas de i den ursprungliga specen får du ta reda på dem empiriskt mot ett skarpt svar. Kontrollera namnen mot verkligheten i stället för att gissa utifrån liknande scheman i samma spec — i det här exemplet heter fälten client/tenant, inte clientName/tenantName som ett närliggande schema använde.

Studion cachar connectorn

Efter pac connector update känner en öppen Studio-session inte till ändringarna. Ladda om sidan. Dyker nya operationer fortfarande inte upp i formelfältets autokomplettering: ta bort datakällan och lägg till den igen.

Uppdaterade svarsscheman plockades däremot upp direkt vid omladdning, utan att datakällan behövde röras.

Bara en flik åt gången kan redigera

Öppnar du appen i en andra flik blir den skrivskyddad, och den första fliken behåller låset tills den stängs. Meddelandet om att du redan har redigeringskontrollen någon annanstans är lätt att missa när du felsöker något helt annat.

Avancerade connector-policies

En situation där standardvägen inte räcker och en policy löser problemet. Den behövs inte för en enkel läsande integration.

Samma HTTP-metod kan inte deklareras två gånger för samma sökväg

Samma GET-endpoint behöver i det här exemplet exponeras både som polling-trigger för Power Automate och som vanlig action för Power Apps. OpenAPI kan bara innehålla en operation per kombination av HTTP-metod och sökväg — GET och POST på samma sökväg går bra, två GET gör det inte.

Lösning
Deklarera en syntetisk sökväg som inte finns hos backend, och låt en routerequesttoendpoint-policy skriva om den till den riktiga sökvägen innan anropet skickas:

# i Swagger: en sökväg som inte finns hos backend
/api/public/v1/integrity/personal-data-processes/list → ListPersonalDataProcesses
# i apiProperties.json: policyn som pekar tillbaka
{
"templateId": "routerequesttoendpoint",
"parameters": {
"x-ms-apimTemplateParameter.newPath": "/api/public/v1/integrity/personal-data-processes",
"x-ms-apimTemplate-operationName": ["ListPersonalDataProcesses"]
}
}

Origin-headern – hantering för Power Apps

DirSys API är i första hand utformat för API- och server-till-server-integrationer. Sådana anrop skickar normalt ingen Origin-header, och DirSys API accepterar därför anrop där Origin saknas.

CORS och Origin är framför allt mekanismer för webbläsarbaserade cross-origin-anrop. DirSys API använder inte Origin för autentisering eller behörighetskontroll. Åtkomst till skyddade resurser styrs separat genom API:ets autentisering och auktorisering.

Power Apps canvas-appar kan däremot skicka en Origin-header som följer med genom den anpassade connectorn, exempelvis:

Origin: https://apps.powerapps.com

DirSys API accepterar inte godtyckliga Origin-headers. Om Power Apps-headern skickas vidare oförändrad kan anropet därför avvisas med:

403 Invalid CORS request

Rekommenderad princip

För DirSys API gäller följande:

  • API-anrop utan Origin ska kunna hanteras normalt.
  • Origin används inte som autentisering eller behörighetskontroll.
  • DirSys behöver inte registrera eller administrera kundspecifika CORS-origins för vanliga API-integrationer.
  • CORS aktiveras endast där direkt cross-origin-åtkomst från en webbläsare uttryckligen ska stödjas.

Det innebär att Power Apps-specifika Origin-headers i första hand bör hanteras i connector-lagret och inte genom att DirSys API öppnas för olika kund- eller Power Platform-origins.

Connector-policy för Power Apps

I den aktuella Power Apps-connectorn hanteras detta genom att den Origin-header som Power Apps skickar skrivs om innan anropet skickas vidare till DirSys API:

"x-ms-apimTemplateParameter.name": "Origin",
"x-ms-apimTemplateParameter.value": "https://api.dirsys.app",
"x-ms-apimTemplateParameter.existsAction": "override"

Policyn förhindrar att Power Apps egen Origin skickas vidare till API:et och utlöser API:ets Origin-kontroll.

Om connector-plattformen medger att Origin-headern tas bort helt är det principiellt en renare lösning, eftersom anropet då får samma beteende som andra server-till-server-integrationer mot DirSys API.

Den aktuella omskrivningen används eftersom connectorns standardpolicy enkelt kan ersätta en header och därmed ger ett förutsägbart beteende utan att DirSys behöver administrera CORS-origins för varje integration.

Kontrollera beteendet

Beteendet kan verifieras mot den öppna health-endpointen och kräver ingen API-nyckel:

curl -s -o /dev/null -w "%{http_code}\n" \
https://api.dirsys.app/api/public/v1/health
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Origin: https://apps.powerapps.com" \
https://api.dirsys.app/api/public/v1/health

Det första anropet saknar Origin och ska normalt accepteras:

200

Det andra innehåller en Origin som API:et inte accepterar och returnerar därför:

403

Om policyn redan finns i connectorn ska den inte tas bort utan att först verifiera hur Power Platform hanterar Origin och att motsvarande anrop fortfarande fungerar mot DirSys API.

Kända begränsningar

Gäller exempelappen i den form guiden beskriver.

  • Max 100 rader. size:100 är API:ets maxvärde per sida. Fler behandlingar än så kräver pagineringslogik i appen.
  • Ingen detaljvy. Pilen på varje rad är gallerilayoutens standard och gör ingenting. GetPersonalDataProcess finns i connectorn men är inte inkopplad.
  • Ingen felnormalisering. API:et svarar med olika felformat beroende på statuskod. Att hantera samtliga enhetligt kräver Power Platforms Custom Code (script.csx).
  • Inga dynamiska dropdowns. ID-fält är vanliga heltalsfält; x-ms-dynamic-values är inte inkopplat.
  • Polling-triggern kan dubbelfyra. Power Automates trigger-mönster förutsätter att servern kan filtrera inkrementellt. Saknas ett updatedAfter-filter hämtas samma poster på nytt vid varje pollning.

Säkerhet och rekommendationer

  • Lagra aldrig nycklar i appen. API-nyckeln hör hemma som securestring i connectorns connection-parametrar — aldrig i en Power Fx-formel, en variabel eller appens källkod.
  • Egen nyckel per integration. Använd en dedikerad integrationsnyckel i stället för att återanvända en personlig, så att den kan spärras utan att slå ut annat.
  • Minsta möjliga behörighet. Ge nyckeln endast de behörigheter (scopes) som integrationen faktiskt behöver. En app som enbart listar data behöver inte skrivrättigheter.
  • Rutin för rotation. Bestäm i förväg hur ofta nyckeln byts och vem som gör det. Planera rotationen i förväg; annars riskerar den att utebli.
  • Var medveten om vad en delad connection döljer. Appens användare delar en integrationsnyckel och framstår som samma identitet mot API:et. Behöver ni kunna skilja grupper åt i loggarna, dela upp i flera nycklar och flera connections i stället för en enda.
  • Granska policies före produktionssättning. En policy modifierar anropet innan det når API:et. Se till att du vet vad varje policy i connectorn gör och varför den finns.

Guiden är skriven utifrån ett faktiskt bygge mot DirSys Public API v1.0.0. Kodexempel och felmeddelanden är hämtade därifrån, inte konstruerade i efterhand. Connectorns källfiler ligger i repot DirSys-PowerPlatform-Connector; exempelappen finns uppackad som YAML i DirSys-PowerApp-Demo och kan importeras till en egen miljö med pac canvas pack.