API d'inventari del Power Platform

L'API d'inventari et permet executar consultes estructurades amb Azure Resource Graph utilitzant una petició POST amb una especificació de consulta al cos de la sol·licitud. L'API tradueix la teva especificació de consulta a Kusto Query Language (KQL) per a l'execució contra Azure Resource Graph. L'API d'inventari per a Recursos forma part de la documentació de referència de l'API de Power Platform. Per a una llista completa de tipus de recursos i camps consultables, consulteu la referència de l'esquema d'inventari de Power Platform.

Autenticació

L'API d'inventari actualment només suporta l'autenticació d'usuari delegada. Aconsegueix un token portador per a un usuari iniciat sessió abans de trucar a l'API.

Important

L'API no suporta l'autenticació només d'aplicació a través d'un principal de servei o una identitat gestionada. Les peticions que utilitzen aquestes identitats retornen HTTP 403 Forbidden.

Per a les instruccions de configuració del token, vegeu Autenticació i utilitzeu un flux d'usuari delegat. El flux principal de servei descrit en aquell article no s'aplica a l'API d'inventari.

Utilitza la línia de comandament de Power Platform (previsualització)

Pots executar consultes de recursos d'inventari des d'un terminal utilitzant l'ordre de previsualització pac resource-query query-resources . La comanda accepta el cos de la sol·licitud de consulta JSON directament o des d'un fitxer.

Punt final de l'API


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

Cos de la sol·licitud

El cos de la sol·licitud ha de contenir una especificació de consulta amb l'estructura següent:

Estructura de la sol·licitud de consulta

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

Propietats

Propietat Tipus Necessari Descripció
TableName cadena Sí El tipus de taula/recurs de destinació a consultar (és a dir, "PowerPlatformResources")
Clauses matriu Sí Matriu de clàusules de consulta que defineixen les operacions a realitzar
Options objecte No Opcions de consulta d'Azure Resource Graph per a la paginació i el control de resultats

Opcions de consulta

L'objecte Options admet paràmetres de consulta Azure Resource Graph per a la paginació i el control de resultats. Consulteu ResourceQueryRequestOptions la documentació per obtenir més informació.

Clàusules de consulta admeses

L'API admet els tipus de clàusules ressaltats en aquesta secció mitjançant la serialització JSON polimòrfica. Cada tipus de clàusula correspon als operadors KQL tal com es documenta a la referència KQL:

Clàusula Where

Filtra les dades en funció de les condicions del camp. Es tradueix a l'operador KQLwhere.

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

Operadors compatibles: L'API admet tots els operadors de cadena i comparació KQL estàndard. Per obtenir una llista completa dels operadors disponibles, vegeu la documentació d'operadors de cadena KQL i operadors numèrics .

Exemple:

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

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

Clàusula de projecte

Selecciona camps específics dels resultats. Es tradueix a l'operador KQLproject.

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

Exemple:

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

Es tradueix a KQL:| project name, properties.displayName, environmentId = tostring(properties.environmentId), createdDate = properties.createdAt

Prendre la clàusula

Limita el nombre de resultats retornats. Es tradueix a l'operador KQLtake.

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

Es tradueix a KQL:| take 50

Ordre per clàusula

Ordena els resultats per camps especificats. Es tradueix a l'operador KQLsort.


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

Exemple:

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

Es tradueix a KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

Clàusula distinta

Retorna valors únics per als camps especificats. Es tradueix a l'operador KQLdistinct.


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

Es tradueix a KQL:| distinct field1, field2

Clàusula de recompte

Retorna el recompte de registres coincidents. Es tradueix a l'operador KQLcount.

{
  "$type": "count"
}

Es tradueix a KQL:| count

Clàusula de resum

Agrega dades mitjançant operacions count o argmax. Es tradueix a l'operador KQLsummarize.

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

Operadors compatibles:

  • count → count() - Compta els registres agrupats per camps especificats.
  • argmax → arg_max() - Obté registres amb el valor màxim al camp especificat.

Exemple de recompte:

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

Es tradueix a KQL:| summarize resourceCount = count() by resourceGroup, type

Exemple d'ArgMax:

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

Es tradueix a KQL:| summarize arg_max(createdTime, *) by resourceGroup

Clàusula d'ampliació

Afegeix columnes calculades als resultats. Es tradueix a l'operador KQLextend.

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

Exemple:

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

Es tradueix a KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) per a les funcions disponibles.

Clàusula d'unió

S'uneix amb una altra taula/subconsulta. Es tradueix a l'operador KQLjoin.


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

Tipus d'unió admesos: L'API admet tots els tipus d'unió KQL. Per obtenir una llista completa dels tipus d'unió disponibles i el seu comportament, vegeu la documentació de l'operador d'unió KQL.

Exemple (unir recursos del Power Platform amb informació de l'entorn):

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

Es tradueix a 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

Exemples de consultes completes

Exemple: consulta bàsica de recursos de Power Platform (patró per defecte del centre d'administració de Power Platform)

Obtingues tots els recursos de Power Platform amb informació d'entorn—aquesta és la consulta per defecte que utilitza el centre d'administració de 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'",
        "'microsoft.powerapps/apps'"
      ]
    },
    {
      "$type": "orderby",
      "FieldNamesAscDesc": {
        "tostring(properties.createdAt)": "desc"
      }
    }
  ]
}

KQL equivalent:

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

Exemple: Compta els recursos de la Power Platform per tipus i ubicació

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

KQL equivalent:

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

Exemple: Consulta simple d'aplicacions de canvas

Obteniu aplicacions de llenç amb filtratge i projecció bàsics:

{
  "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 equivalent:

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

Exemple: Filtra recursos per entorn i interval de dates

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

Es tradueix a 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

Format de resposta

L'API retorna un objecte ResourceQueryResult del Azure Resource Graph SDK. Aquest objecte conté els resultats de la consulta i les metadades sobre l'execució de la consulta.

Estructura de respostes:

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