API de inventário do 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 converte sua especificação de consulta em Kusto Query Language (KQL) para execução em Azure Resource Graph. A API de inventário para recursos faz parte da documentação de referência da API do Power Platform. Para obter uma lista completa de tipos de recursos e campos que podem ser consultados, consulte a referência de esquema de inventário do Power Platform.

Authentication

Atualmente, a API de inventário dá suporte apenas à autenticação de usuário delegada. Obtenha um token de portador para um usuário conectado antes de chamar a API.

Importante

A API não oferece suporte à autenticação exclusiva de aplicativo por meio de uma entidade de serviço ou identidade gerenciada. As solicitações que usam essas identidades retornam HTTP 403 Proibido.

Para obter instruções de configuração de token, consulte Autenticação e use um fluxo de usuário delegado. O fluxo de principal de serviço descrito naquele artigo não se aplica à API de inventário.

Usar a CLI do Power Platform (versão prévia)

Você pode executar consultas de recurso de inventário de um terminal usando o comando de visualização pac resource-query query-resources . O comando aceita o corpo da solicitação JSON de consulta diretamente ou a partir de um arquivo.

Ponto de extremidade da API


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

Corpo da solicitação

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

Propriedades

Propriedade Tipo Obrigatório Description
TableName cadeia Yes O tipo de tabela/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 objeto 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 a parâmetros de consulta do Azure Resource Graph para paginação e controle de resultados. Confira ResourceQueryRequestOptions a documentação para saber mais.

Cláusulas de consulta com suporte

A API dá suporte aos tipos de cláusula realçados 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 em condições de campo. Traduz para o operador KQLwhere.

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

Operadores com suporte: A API dá suporte a todos os operadores de cadeia de caracteres e comparação de KQL padrão. 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 KQLproject.

{
  "$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 KQLtake.

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

Traduz para KQL:| take 50

Ordenar por cláusula

Classifica os resultados por campos especificados. Traduz para o operador KQLsort.


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

Retorna valores exclusivos para campos especificados. Traduz para o operador KQLdistinct.


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

Traduz para KQL:| distinct field1, field2

Cláusula Count

Retorna a contagem de registros correspondentes. Traduz para o operador KQLcount.

{
  "$type": "count"
}

Traduz para KQL:| count

Cláusula Resumo

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

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

Operadores com suporte:

  • count count() → - Contar registros agrupados por campos especificados.
  • argmax arg_max() → – Obter registros com o 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 de 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 KQLextend.

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

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


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

Tipos de junção com suporte: A API dá suporte a 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 (junção de recursos do 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 recurso do Power Platform (padrão padrão do Centro de administração do Power Platform)

Obtenha todos os recursos do Power Platform com informações de ambiente, essa é 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 recursos do 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 de aplicativos Canvas simples

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 retorna um ResourceQueryResult objeto do SDK do Azure Resource Graph. Esse objeto contém os resultados da consulta e os 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
  ]
}
  • Última atualização em