Power Platform-Bestands-API

Mit der Bestands-API können Sie strukturierte Abfragen für Azure Resource Graph mithilfe einer POST-Anforderung mit einer Abfragespezifikation im Anforderungstext ausführen. Die API übersetzt Ihre Abfragespezifikation in Kusto Query Language (KQL) zur Ausführung für Azure Resource Graph. Die Bestands-API für Ressourcen ist Teil der Referenzdokumentation zur Power Platform-API. Eine vollständige Liste der Ressourcentypen und abfragbaren Felder finden Sie unter Power Platform-Bestandsschemareferenz.For a complete list of resource types and queryable fields, see Power Platform inventory schema reference.

Authentication

Die Bestands-API unterstützt derzeit nur delegierte Benutzerauthentifizierung. Rufen Sie ein Bearertoken für einen angemeldeten Benutzer ab, bevor Sie die API aufrufen.

Important

Die API unterstützt die nur-App-Authentifizierung nicht über einen Dienstprinzipal oder eine verwaltete Identität. Anfragen, die diese Identitäten verwenden, führen zu HTTP 403 Forbidden.

Anweisungen zum Einrichten von Token finden Sie unter Authentifizierung und Verwenden eines delegierten Benutzerflusses. Der in diesem Artikel beschriebene Dienstprinzipalfluss gilt nicht für die Bestands-API.

Verwenden der Power Platform CLI (Vorschau)

Sie können Bestandsressourcenabfragen über ein Terminal ausführen, indem Sie den Vorschaubefehl pac resource-query query-resources verwenden. Der Befehl akzeptiert den JSON-Abfrageanforderungstext direkt oder aus einer Datei.

API-Endpunkt


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

Anforderungstext

Der Anforderungstext muss eine Abfragespezifikation mit der folgenden Struktur enthalten:

Abfrageanforderungsstruktur

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

Eigenschaften

Eigenschaft Type Erforderlich Beschreibung
TableName Zeichenfolge Ja Der zu abfragende Zieltabellen-/Ressourcentyp (z. B. "PowerPlatformResources")
Clauses array Ja Array von Abfrageklauseln, die die auszuführenden Vorgänge definieren
Options Objekt Nein Azure Resource Graph-Abfrageoptionen für Seitennummerierung und Ergebniskontrolle

Abfrageoptionen

Das Options Objekt unterstützt Azure Resource Graph-Abfrageparameter für Paginierung und Ergebnissteuerung. Weitere Informationen finden Sie ResourceQueryRequestOptions in der Dokumentation .

Unterstützte Abfrageklauseln

Die API unterstützt die in diesem Abschnitt hervorgehobenen Klauseltypen durch polymorphe JSON-Serialisierung. Jeder Klauseltyp entspricht KQL-Operatoren, wie im KQL-Verweis dokumentiert:

WHERE-Klausel

Filtert Daten basierend auf Feldbedingungen. Wird in den KQL-Operator where übersetzt.

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

Unterstützte Operatoren: Die API unterstützt alle standardmäßigen KQL-Vergleichs- und Zeichenfolgenoperatoren. Eine vollständige Liste der verfügbaren Operatoren finden Sie in der Dokumentation zu KQL-Zeichenfolgenoperatoren und numerischen Operatoren .

Beispiel:

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

Übersetzt in KQL:| where type in~ ('microsoft.powerapps/canvasapps', 'microsoft.copilotstudio/agents')

Project-Klausel

Wählt bestimmte Felder aus den Ergebnissen aus. Wird in den KQL-Operator project übersetzt.

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

Beispiel:

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

Übersetzt in KQL:| project name, properties.displayName, environmentId = tostring(properties.environmentId), createdDate = properties.createdAt

Take-Klausel

Beschränkt die Anzahl der zurückgegebenen Ergebnisse. Wird in den KQL-Operator take übersetzt.

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

Übersetzt in KQL:| take 50

Reihenfolge nach Klausel

Sortiert Ergebnisse nach angegebenen Feldern. Wird in den KQL-Operator sort übersetzt.


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

Beispiel:

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

Übersetzt in KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

Einzigartige Klausel

Gibt eindeutige Werte für angegebene Felder zurück. Wird in den KQL-Operator distinct übersetzt.


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

Übersetzt in KQL:| distinct field1, field2

Zählklausel

Gibt die Anzahl der übereinstimmenden Datensätze zurück. Wird in den KQL-Operator count übersetzt.

{
  "$type": "count"
}

Übersetzt in KQL:| count

Zusammenfassungsklausel

Aggregiert Daten mithilfe von Zähl- oder Argmax-Operationen. Wird in den KQL-Operator summarize übersetzt.

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

Unterstützte Operatoren:

  • count count() → – Zählen von Datensätzen, die nach angegebenen Feldern gruppiert sind.
  • argmax arg_max() → – Abrufen von Datensätzen mit maximalem Wert im angegebenen Feld.

Count-Beispiel:

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

Übersetzt in KQL:| summarize resourceCount = count() by resourceGroup, type

ArgMax-Beispiel:

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

Übersetzt in KQL:| summarize arg_max(createdTime, *) by resourceGroup

Extend-Klausel

Fügt berechnete Spalten zu den Ergebnissen hinzu. Wird in den KQL-Operator extend übersetzt.

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

Beispiel:

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

Übersetzt in KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) für verfügbare Funktionen.

Join-Klausel

Verknüpft mit einer anderen Tabelle/Unterabfrage. Wird in den KQL-Operator join übersetzt.


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

Unterstützte Verknüpfungstypen: Die API unterstützt alle KQL-Verknüpfungstypen. Eine vollständige Liste der verfügbaren Verknüpfungstypen und deren Verhalten finden Sie in der Dokumentation zum KQL-Verknüpfungsoperator.

Beispiel (Verknüpfen von Power Platform-Ressourcen mit Umgebungsinformationen):

{
  "$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"
}

Übersetzt in 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

Vollständige Abfragebeispiele

Beispiel: Grundlegende Power Platform-Ressourcenabfrage (Standardmuster des Power Platform Admin Centers)

Abrufen aller Power Platform-Ressourcen mit Umgebungsinformationen – dies ist die Standardabfrage, die vom Power Platform Admin Center verwendet wird.

{
  "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"
      }
    }
  ]
}

Äquivalente 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

Beispiel: Zählen von Power Platform-Ressourcen nach Typ und Standort

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

Äquivalente KQL:

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

Beispiel: Abfrage für einfache Canvas-Apps

Hol dir Canvas-Apps mit einfacher Filterung und 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
    }
  ]
}

Äquivalente KQL:

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

Beispiel: Filtern von Ressourcen nach Umgebung und Datumsbereich

{
  "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"
      }
    }
  ]
}

Übersetzt in 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

Antwortformat

Die API gibt ein ResourceQueryResult Objekt aus dem Azure Resource Graph SDK zurück. Dieses Objekt enthält die Abfrageergebnisse und Metadaten zur Abfrageausführung.

Antwortstruktur:

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