Bagikan melalui

API inventaris Power Platform

API inventaris memungkinkan Anda menjalankan kueri terstruktur terhadap Azure Resource Graph menggunakan permintaan POST dengan spesifikasi kueri di isi permintaan. API menerjemahkan spesifikasi kueri Anda ke dalam Kusto Query Language (KQL) untuk eksekusi terhadap Azure Resource Graph. API inventori untuk Sumber Daya adalah bagian dari dokumentasi referensi API Power Platform. Untuk daftar lengkap jenis sumber daya dan bidang yang dapat dikueri, lihat Referensi skema inventori Power Platform.

Titik akhir API


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

Badan permintaan

Isi permintaan harus berisi spesifikasi kueri dengan struktur berikut:

Struktur permintaan kueri

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

Karakteristik

Harta benda Tipe Diperlukan Description
TableName string Yes Tabel target/jenis sumber daya untuk dikueri (yaitu, "PowerPlatformResources")
Clauses array Yes Sekumpulan klausa kueri yang menentukan operasi yang akan dilakukan
Options objek Tidak. Azure Resource Graph opsi kueri untuk paginasi dan kontrol hasil

Opsi kueri

Objek Options mendukung parameter kueri Azure Resource Graph untuk penomoran halaman dan kontrol hasil. Lihat ResourceQueryRequestOptions dokumentasi untuk mempelajari selengkapnya.

Klausa kueri yang didukung

API mendukung jenis klausul yang disorot di bagian ini melalui serialisasi JSON polimorfik. Setiap jenis klausul sesuai dengan operator KQL seperti yang didokumenkan dalam referensi KQL:

Klausa di mana

Memfilter data berdasarkan kondisi bidang. Diterjemahkan ke operator KQLwhere.

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

Operator yang didukung: API mendukung semua perbandingan KQL standar dan operator string. Untuk daftar lengkap operator yang tersedia, lihat dokumentasi operator string KQL dan operator numerik.

Example:

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

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

Klausa proyek

Memilih bidang tertentu dari hasil. Diterjemahkan ke operator KQLproject.

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

Example:

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

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

Ambil klausa

Membatasi jumlah hasil yang dikembalikan. Diterjemahkan ke operator KQLtake.

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

Diterjemahkan ke KQL:| take 50

Urutan berdasarkan klausa

Mengurutkan hasil menurut bidang tertentu. Diterjemahkan ke operator KQLsort.


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

Example:

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

Diterjemahkan ke KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

Klausa yang berbeda

Mengembalikan nilai unik untuk bidang tertentu. Diterjemahkan ke operator KQLdistinct.


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

Diterjemahkan ke KQL:| distinct field1, field2

Klausa hitung

Mengembalikan jumlah rekaman yang cocok. Diterjemahkan ke operator KQLcount.

{
  "$type": "count"
}

Diterjemahkan ke KQL:| count

Meringkas klausa

Mengagregasi data menggunakan operasi hitungan atau argmax. Diterjemahkan ke operator KQLsummarize.

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

Operator yang didukung:

  • count count() → - Hitung rekaman yang dikelompokkan menurut bidang tertentu.
  • argmax arg_max() → - Dapatkan rekaman dengan nilai maksimum di bidang yang ditentukan.

Contoh hitung:

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

Diterjemahkan ke KQL:| summarize resourceCount = count() by resourceGroup, type

Contoh ArgMax:

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

Diterjemahkan ke KQL:| summarize arg_max(createdTime, *) by resourceGroup

Perluas klausa

Menambahkan kolom komputasi ke hasil. Diterjemahkan ke operator KQLextend.

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

Example:

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

Diterjemahkan ke KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) untuk fungsi yang tersedia.

Klausa gabungan

Bergabung dengan tabel/subkueri lain. Diterjemahkan ke operator KQLjoin.


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

Jenis gabungan yang didukung: API mendukung semua jenis gabungan KQL. Untuk daftar lengkap jenis gabungan yang tersedia dan perilakunya, lihat dokumentasi operator gabungan KQL.

Contoh (menggabungkan sumber daya Power Platform dengan informasi lingkungan):

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

Diterjemahkan ke 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

Contoh kueri lengkap

Contoh: Kueri sumber daya Dasar Power Platform (pola default pusat administrasi Power Platform)

Dapatkan semua sumber daya Power Platform dengan informasi lingkungan—ini adalah kueri default yang digunakan oleh pusat admin 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 yang setara:

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

Contoh: Menghitung sumber daya Power Platform berdasarkan jenis dan lokasi

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

KQL yang setara:

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

Contoh: Kueri aplikasi kanvas sederhana

Dapatkan aplikasi kanvas dengan pemfilteran dan proyeksi dasar:

{
  "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 yang setara:

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

Contoh: Memfilter sumber daya menurut lingkungan dan rentang tanggal

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

Terjemahan ke 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 Tanggapan

API mengembalikan objek ResourceQueryResult dari SDK Azure Resource Graph. Objek ini berisi hasil kueri dan metadata tentang eksekusi kueri.

Struktur respons:

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