API de inventário da Power Platform

A API de inventário permite executar consultas estruturadas no Azure Resource Graph usando uma solicitação POST com uma especificação de consulta no corpo da solicitação. A API traduz sua especificação de consulta em Kusto Query Language (KQL) para execução no Azure Resource Graph. A API de inventário para Recursos faz parte da documentação de referência da API do Power Platform. Para uma lista completa de tipos de recursos e campos consultáveis, consulte a referência do esquema de inventário do Power Platform.

Authentication

Atualmente, a API de inventário suporta apenas autenticação delegada de utilizadores. Obtenha um token portador para um utilizador iniciado sessão antes de chamar a API.

Importante

A API não suporta autenticação apenas por aplicação através de um principal de serviço ou identidade gerida. Os pedidos que utilizam estas identidades devolvem HTTP 403 Forbidden.

Para instruções de configuração do token, consulte Autenticação e utilize um fluxo de utilizador delegado. O fluxo principal do serviço descrito nesse artigo não se aplica à API de inventário.

Utilize a CLI do Power Platform (pré-visualização)

Podes executar consultas de recursos de inventário a partir de um terminal usando o comando de pré-visualização pac resource-query query-resources . O comando aceita o corpo do pedido de consulta JSON diretamente ou a partir de um ficheiro.

Ponto final de API


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

Corpo do pedido

O corpo da solicitação deve conter uma especificação de consulta com a seguinte estrutura:

Estrutura de solicitação de consulta

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

Properties

Propriedade Tipo Obrigatório Description
TableName cadeia (de caracteres) Yes A tabela/tipo de recurso de destino a ser consultado (ou seja, "PowerPlatformResources")
Clauses matriz Yes Matriz de cláusulas de consulta que definem as operações a serem executadas
Options objecto No Opções de consulta do Azure Resource Graph para paginação e controle de resultados

Opções de consulta

O Options objeto dá suporte aos parâmetros de consulta do Azure Resource Graph para paginação e controle de resultados. Consulte ResourceQueryRequestOptions a documentação para saber mais.

Cláusulas de consulta suportadas

A API suporta os tipos de cláusula destacados nesta seção por meio da serialização JSON polimórfica. Cada tipo de cláusula corresponde aos operadores KQL, conforme documentado na referência KQL:

Cláusula Where

Filtra dados com base nas condições de campo. Traduz para o operador KQL where.

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

Operadores suportados: A API suporta todos os operadores padrão de comparação e cadeia de caracteres KQL. Para obter uma lista completa dos operadores disponíveis, consulte a documentação dos operadores de cadeia de caracteres KQL e dos operadores numéricos .

Example:

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

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

Cláusula de projeto

Seleciona campos específicos dos resultados. Traduz para o operador KQL project.

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

Example:

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

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

Cláusula Take

Limita o número de resultados retornados. Traduz para o operador KQL take.

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

Traduz para KQL:| take 50

Ordem por cláusula

Classifica os resultados por campos especificados. Traduz para o operador KQL sort.


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

Example:

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

Traduz para KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

Cláusula distinta

Retorna valores exclusivos para campos especificados. Traduz para o operador KQL distinct.


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

Traduz para KQL:| distinct field1, field2

Cláusula de contagem

Devolve a contagem de registos correspondentes. Traduz para o operador KQL count.

{
  "$type": "count"
}

Traduz para KQL:| count

Cláusula de resumo

Agrega dados usando operações de contagem ou argmax. Traduz para o operador KQL summarize.

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

Operadores suportados:

  • count count() → - Contar registros agrupados por campos especificados.
  • argmax arg_max() → - Obter registros com valor máximo no campo especificado.

Exemplo de contagem:

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

Traduz para KQL:| summarize resourceCount = count() by resourceGroup, type

Exemplo do ArgMax:

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

Traduz para KQL:| summarize arg_max(createdTime, *) by resourceGroup

Cláusula de extensão

Adiciona colunas computadas aos resultados. Traduz para o operador KQL extend.

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

Example:

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

Traduz para KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) para funções disponíveis.

Cláusula de adesão

Une-se a outra tabela/subconsulta. Traduz para o operador KQL join.


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

Tipos de adesão suportados: A API suporta todos os tipos de junção KQL. Para obter uma lista completa dos tipos de junção disponíveis e seu comportamento, consulte a documentação do operador de junção KQL.

Exemplo (unir recursos da Power Platform com informações de 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"
}

Traduz para 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

Exemplos de consulta completos

Exemplo: Consulta básica de recursos Power Platform (padrão padrão do centro de administração Power Platform)

Obtenha todos os recursos do Power Platform com informações de ambiente — esta é a consulta padrão usada pelo centro de administração do 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 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', 'microsoft.powerapps/apps')
| order by tostring(properties.createdAt) desc

Exemplo: Contar os recursos da Power Platform por tipo e localização

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

Exemplo: Consulta simples de aplicações canvas

Obtenha aplicativos de tela com filtragem e projeção básicas:

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

Exemplo: Filtrar recursos por ambiente e intervalo de datas

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

Traduz para 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 da resposta

A API devolve um objeto ResourceQueryResult do SDK Azure Resource Graph. Este objeto contém os resultados da consulta e metadados sobre a execução da consulta.

Estrutura de resposta:

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