Power Platform-lager-API

Lager-API'en giver dig mulighed for at udføre strukturerede forespørgsler mod Azure Resource Graph ved hjælp af en POST-anmodning med en forespørgselsspecifikation i anmodningens brødtekst. API'en oversætter din forespørgselsspecifikation til Kusto Query Language (KQL) til udførelse i forhold til Azure Resource Graph. Lager-API'en for Ressourcer er en del af referencedokumentationen til Power Platform API. Du kan se en komplet liste over ressourcetyper og felter, der kan forespørges på, under Reference til Power Platform-lagerskema.

Godkendelse

Lager-API'en understøtter i øjeblikket kun delegeret brugergodkendelse. Hent et ihændehavertoken for en bruger, der er logget på, før du kalder API'en.

Vigtigt!

API'en understøtter ikke godkendelse kun af apps via en tjenesteprincipal eller administreret identitet. Anmodninger, der bruger disse identiteter, returnerer HTTP 403 Forbudt.

Du kan finde instruktioner til konfiguration af token under Godkendelse og brug et delegeret brugerflow. Det flow for tjenesteprincipalen, der er beskrevet i denne artikel, gælder ikke for lager-API'en.

Brug Power Platform-kommandolinjegrænsefladen (prøveversion)

Du kan køre forespørgsler om lagerressourcer fra en terminal ved hjælp af eksempelkommandoen pac resource-query query-resources . Kommandoen accepterer brødteksten i JSON-forespørgslen direkte eller fra en fil.

API-slutpunkt


POST {PowerPlatformAPI url}/resourcequery/resources/query?api-version=2024-10-01

Anmodningstekst

Anmodningens brødtekst skal indeholde en forespørgselsspecifikation med følgende struktur:

Struktur for forespørgselsanmodning

{
  "TableName": "string",
  "Clauses": [
    {
      "$type": "clause_type",
      // clause-specific properties
    }
  ],
  "Options": {
    "Top": 100,
    "Skip": 0,
    "SkipToken": "string"
  }
}

Egenskaber

Egenskab Type Obligatorisk Beskrivelse
TableName streng Ja Den destinationstabel/ressourcetype, der skal forespørges om (f.eks. "PowerPlatformResources")
Clauses matrix Ja Matrix af forespørgselsklausuler, der definerer de handlinger, der skal udføres
Options objekt Nej Forespørgselsindstillinger for Azure Resource Graph til sideinddeling og resultatkontrol

Forespørgselsindstillinger

Objektet Options understøtter Azure Resource Graph forespørgselsparametre for sideinddeling og resultatkontrol. Se ResourceQueryRequestOptions dokumentationen for at få mere at vide.

Understøttede forespørgselsklausuler

API'en understøtter de delsætningstyper, der er fremhævet i dette afsnit, via polymorf JSON-serialisering. Hver delsætningstype svarer til KQL-operatorer som dokumenteret i KQL-referencen:

Where-delsætning

Filtrerer data baseret på feltbetingelser. Oversætter til KQL-operatorenwhere.

{
  "$type": "where",
  "FieldName": "string",
  "Operator": "string",
  "Values": ["string1", "string2"]
}

Understøttede operatorer: API'en understøtter alle KQL-standardsammenlignings- og strengoperatorer. Du kan se en komplet liste over tilgængelige operatorer i dokumentationen til KQL-strengoperatorer og numeriske operatorer .

Eksempel:

{
  "$type": "where",
  "FieldName": "type",
  "Operator": "in~",
  "Values": ["'microsoft.powerapps/canvasapps'", "'microsoft.copilotstudio/agents'"]
}

Oversætter til KQL:| where type in~ ('microsoft.powerapps/canvasapps', 'microsoft.copilotstudio/agents')

Projektdelsætning

Vælger bestemte felter fra resultaterne. Oversætter til KQL-operatorenproject.

{
  "$type": "project",
  "FieldList": ["field1", "field2", "field3"]
}

Eksempel:

{
  "$type": "project",
  "FieldList": [
    "name", 
    "properties.displayName", 
    "environmentId = tostring(properties.environmentId)",
    "createdDate = properties.createdAt"
  ]
}

Oversætter til KQL:| project name, properties.displayName, environmentId = tostring(properties.environmentId), createdDate = properties.createdAt

Udtagningsklausul

Begrænser antallet af returnerede resultater. Oversætter til KQL-operatorentake.

{
  "$type": "take",
  "TakeCount": 50
}

Oversætter til KQL:| take 50

ORDER BY-klausul

Sorterer resultater efter angivne felter. Oversætter til KQL-operatorensort.


{
  "$type": "orderby",
  "FieldNamesAscDesc": {
    "field1": "asc",
    "field2": "desc"
  }
}

Eksempel:

{
  "$type": "orderby",
  "FieldNamesAscDesc": {
    "tostring(properties.createdAt)": "desc",
    "properties.displayName": "asc"
  }
}

Oversætter til KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

Distinct klausul

Returnerer entydige værdier for angivne felter. Oversætter til KQL-operatorendistinct.


{
  "$type": "distinct",
  "FieldList": ["field1", "field2"]
}

Oversætter til KQL:| distinct field1, field2

Tæl betingelse

Returnerer antallet af samsvarende poster. Oversætter til KQL-operatorencount.

{
  "$type": "count"
}

Oversætter til KQL:| count

Opsummer delsætning

Aggregerer data ved hjælp af handlingerne count eller argmax. Oversætter til KQL-operatorensummarize.

{
  "$type": "summarize",
  "SummarizeClauseExpression": {
    "OperatorName": "count|argmax",
    "OperatorFieldName": "string",
    "FieldList": ["field1", "field2"]
  }
}

Understøttede operatorer:

  • count count() → – Antal poster, der er grupperet efter angivne felter.
  • argmax → arg_max() – Hent poster med maksimum værdi i det angivne felt.

Eksempel på antal:

{
  "$type": "summarize",
  "SummarizeClauseExpression": {
    "OperatorName": "count",
    "OperatorFieldName": "resourceCount",
    "FieldList": ["resourceGroup", "type"]
  }
}

Oversætter til KQL:| summarize resourceCount = count() by resourceGroup, type

ArgMax-eksempel:

{
  "$type": "summarize",
  "SummarizeClauseExpression": {
    "OperatorName": "argmax",
    "OperatorFieldName": "createdTime",
    "FieldList": ["resourceGroup"]
  }
}

Oversætter til KQL:| summarize arg_max(createdTime, *) by resourceGroup

Udvid delsætning

Føjer beregnede kolonner til resultaterne. Oversætter til KQL-operatorenextend.

{
  "$type": "extend",
  "FieldName": "newFieldName",
  "Expression": "KQL_EXPRESSION"
}

Eksempel:

{
  "$type": "extend",
  "FieldName": "environmentId",
  "Expression": "tostring(properties.environmentId)"
}

Oversætter til KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) til tilgængelige funktioner.

Join-parameter

Forener med en anden tabel eller underforespørgsel. Oversætter til KQL-operatorenjoin.


{
  "$type": "join",
  "RightTable": {
    "TableName": "string",
    "Clauses": []
  },
  "JoinKind": "string",
    "LeftColumnName": "string",
  "RightColumnName": "string"
}

Understøttede joinforbindelser: API'en understøtter alle KQL-joinforbindelser. Du kan se en komplet liste over tilgængelige jointyper og deres funktionsmåde i dokumentationen til KQL-joinoperatoren.

Eksempel (sammenføjning af Power Platform-ressourcer med miljøoplysninger):

{
  "$type": "join",
  "JoinKind": "leftouter",
  "RightTable": {
    "TableName": "PowerPlatformResources",
    "Clauses": [
      {
        "$type": "where",
        "FieldName": "type",
        "Operator": "==",
        "Values": ["'microsoft.powerplatform/environments'"]
      },
      {
        "$type": "project",
        "FieldList": [
          "environmentId = name",
          "environmentName = properties.displayName",
          "environmentRegion = location",
          "environmentType = properties.environmentType",
          "isManagedEnvironment = properties.isManaged"
        ]
      }
    ]
  },
  "LeftColumnName": "environmentId",
  "RightColumnName": "environmentId"
}

Oversætter til KQL:| join kind=leftouter (PowerPlatformResources | where type == 'microsoft.powerplatform/environments' | project environmentId = name, environmentName = properties.displayName, environmentRegion = location, environmentType = properties.environmentType, isManagedEnvironment = properties.isManaged) on $left.environmentId == $right.environmentId

Komplette forespørgselseksempler

Eksempel: Grundlæggende Power Platform-ressourceforespørgsel (Standardmønster for Power Platform Administration)

Hent alle Power Platform-ressourcer med miljøoplysninger – dette er den standardforespørgsel, der bruges af Power Platform Administration.

{
  "Options": {
    "Top": 1000,
    "Skip": 0,
    "SkipToken": ""
  },
  "TableName": "PowerPlatformResources",
  "Clauses": [
    {
      "$type": "extend",
      "FieldName": "joinKey",
      "Expression": "tolower(tostring(properties.environmentId))"
    },
    {
      "$type": "join",
      "JoinKind": "leftouter",
      "RightTable": {
        "TableName": "PowerPlatformResources",
        "Clauses": [
          {
            "$type": "where",
            "FieldName": "type",
            "Operator": "==",
            "Values": ["'microsoft.powerplatform/environments'"]
          },
            {
            "$type": "project",
            "FieldList": [
              "joinKey = tolower(name)",
              "environmentName = properties.displayName",
              "environmentRegion = location",
              "environmentType = properties.environmentType",
              "isManagedEnvironment = properties.isManaged"
            ]
          }
        ]
      },
      "LeftColumnName": "joinKey",
      "RightColumnName": "joinKey"
    },
    {
      "$type": "where",
      "FieldName": "type",
      "Operator": "in~",
      "Values": [
        "'microsoft.powerapps/canvasapps'",
        "'microsoft.powerapps/modeldrivenapps'",
        "'microsoft.powerautomate/cloudflows'",
        "'microsoft.copilotstudio/agents'",
        "'microsoft.powerautomate/agentflows'",
        "'microsoft.powerapps/codeapps'",
        "'microsoft.powerapps/apps'"
      ]
    },
    {
      "$type": "orderby",
      "FieldNamesAscDesc": {
        "tostring(properties.createdAt)": "desc"
      }
    }
  ]
}

Tilsvarende KQL:

PowerPlatformResources
| extend joinKey = tolower(tostring(properties.environmentId))
| join kind=leftouter (
    PowerPlatformResources
    | where type == 'microsoft.powerplatform/environments'
    | project joinKey = tolower(name), environmentName = properties.displayName, environmentRegion = location, environmentType = properties.environmentType, isManagedEnvironment = properties.isManaged
  ) on $left.joinKey == $right.joinKey
| where type in~ ('microsoft.powerapps/canvasapps', 'microsoft.powerapps/modeldrivenapps', 'microsoft.powerautomate/cloudflows', 'microsoft.copilotstudio/agents', 'microsoft.powerautomate/agentflows', 'microsoft.powerapps/codeapps', 'microsoft.powerapps/apps')
| order by tostring(properties.createdAt) desc

Eksempel: Tæl Power Platform-ressourcer efter type og placering

{
  "TableName": "PowerPlatformResources",
  "Clauses": [
    {
      "$type": "summarize",
      "SummarizeClauseExpression": {
        "OperatorName": "count",
        "OperatorFieldName": "resourceCount",
        "FieldList": ["type", "location"]
      }
    },
    {
      "$type": "orderby",
      "FieldNamesAscDesc": {
        "resourceCount": "desc"
      }
    }
  ]
}

Tilsvarende KQL:

PowerPlatformResources
| summarize resourceCount = count() by type, location
| sort by resourceCount desc

Eksempel: Simpel forespørgsel efter canvas-apper

Hent lærredsapps med grundlæggende filtrering og projektion:

{
  "TableName": "PowerPlatformResources",
  "Clauses": [
    {
      "$type": "where",
      "FieldName": "type",
      "Operator": "==",
      "Values": ["'microsoft.powerapps/canvasapps'"]
    },
    {
      "$type": "project",
      "FieldList": [
        "name",
        "location",
        "properties.displayName",
        "properties.createdAt",
        "properties.environmentId"
      ]
    },
    {
      "$type": "take",
      "TakeCount": 100
    }
  ]
}

Tilsvarende KQL:

PowerPlatformResources
| where type == 'microsoft.powerapps/canvasapps'
| project name, location, properties.displayName, properties.createdAt, properties.environmentId
| take 100

Eksempel: Filtrer ressourcer efter miljø og datointerval

{
  "TableName": "PowerPlatformResources",
  "Clauses": [
    {
      "$type": "where",
      "FieldName": "type",
      "Operator": "==",
      "Values": ["'microsoft.powerapps/canvasapps'"]
    },
    {
      "$type": "where",
      "FieldName": "properties.environmentId",
      "Operator": "==",
      "Values": ["your-environment-id"]
    },
    {
      "$type": "extend",
      "FieldName": "createdDate",
      "Expression": "todatetime(properties.createdAt)"
    },
    {
      "$type": "where",
      "FieldName": "createdDate",
      "Operator": ">=",
      "Values": ["datetime(2024-01-01)"]
    },
    {
      "$type": "project",
      "FieldList": [
        "name",
        "properties.displayName",
        "properties.createdAt",
        "properties.createdBy",
        "properties.ownerId"
      ]
    },
    {
      "$type": "orderby",
      "FieldNamesAscDesc": {
        "createdDate": "desc"
      }
    }
  ]
}

Oversætter til KQL:

PowerPlatformResources
| where type == 'microsoft.powerapps/canvasapps'
| where properties.environmentId == "your-environment-id"
| extend createdDate = todatetime(properties.createdAt)
| where createdDate >= datetime(2024-01-01)
| project name, properties.displayName, properties.createdAt, properties.createdBy, properties.ownerId
| sort by createdDate desc

Svarformat

API'en returnerer et ResourceQueryResult objekt fra Azure Resource Graph SDK. Dette objekt indeholder forespørgselsresultater og metadata om udførelse af forespørgslen.

Svarstruktur:

{
  "totalRecords": 1250,
  "count": 50,
  "resultTruncated": 1,
  "skipToken": "string_for_next_page",
  "data": [
    // Array of result objects based on your query
  ]
}
  • Sidst opdateret den