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
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.
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.
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.
winget install Microsoft.PowerAppsCLI. Kommandot heter pac.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.
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".
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.
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.
Verifiera att API:t, autentiseringen och connectorn fungerar innan Power Apps och Power Fx blandas in. Då vet du var ett eventuellt fel sitter.
ListPersonalDataProcesses..data med en array av poster — det är den nivån appen kommer att binda mot.
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.
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":
| Kontroll | Egenskap | Formel |
|---|---|---|
| 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") |
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.
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.
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
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.
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.
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.
Fyra fel där felmeddelandet inte pekade på den verkliga orsaken.
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.
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.
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.
Ö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.
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 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"]
}
}
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
För DirSys API gäller följande:
Origin ska kunna hanteras normalt.Origin används inte som autentisering eller behörighetskontroll.
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.
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.
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.
Gäller exempelappen i den form guiden beskriver.
size:100 är API:ets maxvärde per sida. Fler behandlingar än så kräver pagineringslogik i appen.GetPersonalDataProcess finns i connectorn men är inte inkopplad.script.csx).x-ms-dynamic-values är inte inkopplat.updatedAfter-filter hämtas samma poster på nytt vid varje pollning.securestring i connectorns connection-parametrar — aldrig i en Power Fx-formel, en variabel eller appens källkod.
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.