API di inventario di Power Platform

L'API di inventario consente di eseguire query strutturate su Azure Resource Graph usando una richiesta POST con una specifica di query nel corpo della richiesta. L'API converte la specifica della query in Linguaggio di query Kusto (KQL) per l'esecuzione in Azure Resource Graph. L'API di inventario per le risorse fa parte della documentazione di riferimento dell'API Power Platform. Per un elenco completo dei tipi di risorse e dei campi su cui è possibile eseguire query, vedere Informazioni di riferimento sullo schema di inventario di Power Platform.

Punto finale API


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

Corpo della richiesta

Il corpo della richiesta deve contenere una specifica di query con la struttura seguente:

Struttura della richiesta di query

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

Proprietà

Proprietà Type Obbligatorio Description
TableName corda Yes Tipo di tabella/risorsa di destinazione su cui eseguire una query,ad esempio "PowerPlatformResources"
Clauses array Yes Matrice di clausole di query che definiscono le operazioni da eseguire
Options object No Opzioni di query di Azure Resource Graph per la paginazione e il controllo dei risultati

Opzioni di query

L'oggetto Options supporta i parametri di query di Azure Resource Graph per la paginazione e il controllo dei risultati. Per altre informazioni, vedere ResourceQueryRequestOptions la documentazione .

Clausole di query supportate

L'API supporta i tipi di clausola evidenziati in questa sezione tramite la serializzazione JSON polimorfica. Ogni tipo di clausola corrisponde agli operatori KQL, come documentato nel riferimento KQL:

Condizione Where

Filtra i dati in base alle condizioni dei campi. Converte nell'operatore KQLwhere.

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

Operatori supportati: L'API supporta tutti gli operatori di confronto e stringa KQL standard. Per un elenco completo degli operatori disponibili, vedere la documentazione relativa agli operatori stringa KQL e agli operatori numerici .

Esempio:

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

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

Clausola del progetto

Seleziona campi specifici dai risultati. Converte nell'operatore KQLproject.

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

Esempio:

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

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

Clausola di Accettazione

Limita il numero di risultati restituiti. Converte nell'operatore KQLtake.

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

Converte in KQL:| take 50

Clausola "ORDER BY"

Ordina i risultati in base ai campi specificati. Converte nell'operatore KQLsort.


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

Esempio:

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

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

Clausola Distinta

Restituisce valori univoci per i campi specificati. Converte nell'operatore KQLdistinct.


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

Converte in KQL:| distinct field1, field2

Clausola di conteggio

Restituisce il conteggio dei record corrispondenti. Converte nell'operatore KQLcount.

{
  "$type": "count"
}

Converte in KQL:| count

Clausola Riassunti

Aggrega i dati usando operazioni count o argmax. Converte nell'operatore KQLsummarize.

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

Operatori supportati:

  • count count() → : conteggio dei record raggruppati in base ai campi specificati.
  • argmax arg_max() → : ottenere record con valore massimo nel campo specificato.

Esempio di conteggio:

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

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

Esempio di ArgMax:

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

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

Clausola Estendi

Aggiunge colonne calcolate ai risultati. Converte nell'operatore KQLextend.

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

Esempio:

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

Converte in KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) per le funzioni disponibili.

Clausola Join

Unisce con un'altra tabella/sotto-interrogazione. Converte nell'operatore KQLjoin.


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

Tipi di join supportati: L'API supporta tutti i tipi di join KQL. Per un elenco completo dei tipi di join disponibili e del relativo comportamento, vedere la documentazione dell'operatore join KQL.

Esempio (unione di risorse di Power Platform con informazioni sull'ambiente):

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

Converte 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

Esempi di query completi

Esempio: Query di risorse di base di Power Platform (modello predefinito del centro amministrativo di Power Platform)

Ottenere tutte le risorse di Power Platform con informazioni sull'ambiente, ovvero la query predefinita usata dall'interfaccia di amministrazione di Power Platform.

{
  "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'"
      ]
    },
    {
      "$type": "orderby",
      "FieldNamesAscDesc": {
        "tostring(properties.createdAt)": "desc"
      }
    }
  ]
}

KQL equivalente:

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')
| order by tostring(properties.createdAt) desc

Esempio: Contare le risorse di Power Platform per tipo e posizione

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

KQL equivalente:

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

Esempio: Query di app canvas semplici

Ottenere app canvas con filtro e proiezione di base:

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

KQL equivalente:

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

Esempio: Filtrare le risorse in base all'ambiente e all'intervallo di date

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

Converte 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

Formato della risposta

L'API restituisce un oggetto ResourceQueryResult dall'SDK di Azure Resource Graph. Questo oggetto contiene i risultati della query e i metadati relativi all'esecuzione della query.

Struttura della risposta:

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