API สินค้าคงคลังของ Power Platform

API สินค้าคงคลังช่วยให้คุณสามารถดําเนินการคิวรีที่มีโครงสร้างกับ Azure Resource Graph โดยใช้คําขอ POST พร้อมข้อมูลจําเพาะของคิวรีในเนื้อความของคําขอ API แปลข้อมูลจําเพาะของคิวรีคุณเป็น Kusto Query Language (KQL) สําหรับการดําเนินการกับ Azure Resource Graph API สินค้าคงคลังสําหรับทรัพยากรเป็นส่วนหนึ่งของเอกสารอ้างอิง Power Platform API สําหรับรายการทั้งหมดของชนิดทรัพยากรและเขตข้อมูลที่สามารถคิวรีได้ โปรดดูที่ การอ้างอิง Schema สินค้าคงคลังของ Power Platform

ปลายทาง API

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

เนื้อหาของคำขอ

เนื้อความคําขอต้องมีข้อมูลจําเพาะของคิวรีที่มีโครงสร้างต่อไปนี้:

โครงสร้างคําขอคิวรี

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

คุณสมบัติ

ทรัพย์สิน	ประเภท	ต้องมี	คำอธิบาย
TableName	สตริง	ได้	ชนิดตาราง/ทรัพยากรเป้าหมายสําหรับคิวรี (เช่น "PowerPlatformResources")
Clauses	อาร์เรย์	ได้	อาร์เรย์ของคำสั่งคิวรีที่กำหนดการดำเนินการ
Options	ออบเจ็กต์	ไม่	Azure Resource Graph ตัวเลือกคิวรีสําหรับการควบคุมการแบ่งหน้าและผลลัพธ์

ตัวเลือกคิวรี

วัตถุ Options สนับสนุนพารามิเตอร์คิวรี Azure Resource Graph สําหรับการควบคุมการแบ่งหน้าและผลลัพธ์ ดู ResourceQueryRequestOptions เอกสาร เพื่อเรียนรู้เพิ่มเติม

คำสั่งคิวรีที่ได้รับการสนับสนุน

API สนับสนุนประเภทส่วนคําสั่งที่เน้นในส่วนนี้ผ่านการจัดเรียงแบบอนุกรม JSON polymorphic ส่วนคําสั่งแต่ละชนิดสอดคล้องกับตัวดําเนินการ KQL ตามที่ระบุไว้ใน การอ้างอิง KQL:

ส่วนคําสั่ง Where

กรองข้อมูลตามเงื่อนไขของเขตข้อมูล แปลเป็นโอเปอเรเตอร์ KQL where

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

ตัวดําเนินการที่สนับสนุน: API สนับสนุนตัวดําเนินการเปรียบเทียบ KQL และสตริงมาตรฐานทั้งหมด สําหรับรายการทั้งหมดของตัวดําเนินการที่พร้อมใช้งาน โปรดดูเอกสารประกอบ ตัวดําเนินการสตริง KQL และ ตัวดําเนินการตัวเลข

ตัวอย่าง:

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

แปลเป็น KQL:| where type in~ ('microsoft.powerapps/canvasapps', 'microsoft.copilotstudio/agents')

ข้อโครงการ

เลือกเขตข้อมูลเฉพาะจากผลลัพธ์ แปลเป็นโอเปอเรเตอร์ KQL project

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

ตัวอย่าง:

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

แปลเป็น KQL:| project name, properties.displayName, environmentId = tostring(properties.environmentId), createdDate = properties.createdAt

ใช้ส่วนคําสั่ง

จํากัดจํานวนของผลลัพธ์ที่ส่งกลับ แปลเป็นโอเปอเรเตอร์ KQL take

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

แปลเป็น KQL:| take 50

ลําดับตามส่วนคําสั่ง

เรียงลําดับผลลัพธ์ตามเขตข้อมูลที่ระบุ แปลเป็นโอเปอเรเตอร์ KQL sort

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

ตัวอย่าง:

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

แปลเป็น KQL:| sort by tostring(properties.createdAt) desc, properties.displayName asc

ส่วนคําสั่ง Distinct

แสดงค่าที่ไม่ซ้ํากันสําหรับเขตข้อมูลที่ระบุ แปลเป็นโอเปอเรเตอร์ KQL distinct

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

แปลเป็น KQL:| distinct field1, field2

คําสั่งการนับ

แสดงจํานวนเรกคอร์ดที่ตรงกัน แปลเป็นโอเปอเรเตอร์ KQL count

{
  "$type": "count"
}

แปลเป็น KQL:| count

สรุปข้อกำหนด

รวมข้อมูลโดยใช้การดําเนินการนับจํานวนหรือ argmax แปลเป็นโอเปอเรเตอร์ KQL summarize

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

ตัวดําเนินการที่สนับสนุน:

• count count() → - นับจํานวนระเบียนที่จัดกลุ่มตามเขตข้อมูลที่ระบุ
• argmax arg_max() → - รับระเบียนที่มีค่าสูงสุดในเขตข้อมูลที่ระบุ

ตัวอย่างการนับ:

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

แปลเป็น KQL:| summarize resourceCount = count() by resourceGroup, type

ตัวอย่าง ArgMax:

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

แปลเป็น KQL:| summarize arg_max(createdTime, *) by resourceGroup

ขยายส่วนคําสั่ง

เพิ่มคอลัมน์ที่คํานวณไปยังผลลัพธ์ แปลเป็นโอเปอเรเตอร์ KQL extend

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

ตัวอย่าง:

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

แปลเป็น KQL:| extend environmentId = tostring(properties.environmentId)https://docs.microsoft.com/en-us/azure/data-explorer/kusto/query/scalarfunctions) สําหรับฟังก์ชันที่พร้อมใช้งาน

ส่วนคําสั่งการรวม

รวมกับตาราง/คิวรีย่อยอื่น แปลเป็นโอเปอเรเตอร์ KQL join

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

ชนิดการรวมที่สนับสนุน: API สนับสนุนชนิดการรวม KQL ทั้งหมด สําหรับรายการทั้งหมดของชนิดการรวมที่พร้อมใช้งานและลักษณะการทํางาน ดูเอกสารประกอบตัวดําเนินการรวม KQL

ตัวอย่าง (การเข้าร่วมทรัพยากร Power Platform ด้วยข้อมูลสภาพแวดล้อม):

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

แปลเป็น 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

ตัวอย่างคิวรีที่เสร็จสมบูรณ์

ตัวอย่าง: คิวรีแหล่งข้อมูล Power Platform พื้นฐาน (รูปแบบเริ่มต้นของศูนย์การจัดการ Power Platform)

รับแหล่งข้อมูล Power Platform ทั้งหมดที่มีข้อมูลสภาพแวดล้อม —นี่คือคิวรีเริ่มต้นที่ใช้โดยศูนย์การจัดการ 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 ที่เทียบเท่า:

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

ตัวอย่าง: นับจํานวนทรัพยากร Power Platform ตามชนิดและตําแหน่งที่ตั้ง

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

KQL ที่เทียบเท่า:

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

ตัวอย่าง: คิวรีแอปพื้นที่ทํางานแบบง่าย

รับแอปแคนวาสที่มีการกรองและการแสดงผลขั้นพื้นฐาน:

{
  "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 ที่เทียบเท่า:

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

ตัวอย่าง: กรองทรัพยากรตามสภาพแวดล้อมและช่วงวันที่

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

แปลเป็น 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

รูปแบบการตอบ

API ส่งกลับออบเจ็กต์ ResourceQueryResult จาก Azure Resource Graph SDK วัตถุนี้ประกอบด้วยผลลัพธ์คิวรีและเมตาดาต้าเกี่ยวกับการดําเนินการคิวรี

โครงสร้างการตอบสนอง:

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