واجهة برمجة تطبيقات مخزون Power Platform

تسمح لك واجهة برمجة تطبيقات المخزون بتنفيذ الاستعلامات المنظمة مقابل Azure Resource Graph باستخدام طلب POST مع مواصفات استعلام في نص الطلب. تترجم واجهة برمجة التطبيقات مواصفات الاستعلام إلى Kusto Query Language (KQL) للتنفيذ مقابل Azure Resource Graph. تعد واجهة برمجة تطبيقات المخزون للموارد جزءا من الوثائق المرجعية لواجهة برمجة تطبيقات Power Platform. للحصول على قائمة كاملة وأنواع الموارد والحقول القابلة للاستعلام، راجع مرجع مخطط مخزون Power Platform.

نقطة نهاية واجهة برمجة التطبيقات

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 الوثائق لمعرفة المزيد.

عبارات الاستعلام المدعومة

تدعم واجهة برمجة التطبيقات أنواع العبارات المميزة في هذا القسم من خلال تسلسل JSON متعدد الأشكال. يتوافق كل نوع عبارة مع عوامل تشغيل KQL كما هو موثق في مرجع KQL:

شرط Where

تصفية البيانات استنادا إلى شروط الحقل. يترجم إلى عامل تشغيل KQLwhere.

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

عوامل التشغيل المدعومة: تدعم واجهة برمجة التطبيقات جميع عوامل تشغيل سلسلة ومقارنة 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')

بند المشروع

تحديد حقول معينة من النتائج. يترجم إلى عامل تشغيل KQLproject.

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

عبارة استحواذ

يحد من عدد النتائج التي تم إرجاعها. يترجم إلى عامل تشغيل KQLtake.

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

يترجم إلى KQL:| take 50

ترتيب حسب عبارة

فرز النتائج حسب الحقول المحددة. يترجم إلى عامل تشغيل KQLsort.

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

عبارة مميزة

إرجاع قيم فريدة لحقول محددة. يترجم إلى عامل تشغيل KQLdistinct.

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

يترجم إلى KQL:| distinct field1, field2

عبارة العد

إرجاع عدد السجلات المطابقة. يترجم إلى عامل تشغيل KQLcount.

{
  "$type": "count"
}

يترجم إلى KQL:| count

جملة التلخيص

تجميع البيانات باستخدام عمليات العد أو argmax. يترجم إلى عامل تشغيل KQLsummarize.

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

توسيع عبارة

يضيف أعمدة محسوبة إلى النتائج. يترجم إلى عامل تشغيل KQLextend.

{
  "$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) للوظائف المتوفرة.

عبارة الانضمام

يندمج مع جدول أو استعلام فرعي آخر. يترجم إلى عامل تشغيل KQLjoin.

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

أنواع الانضمام المدعومة: تدعم واجهة برمجة التطبيقات جميع أنواع الانضمام إلى 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

تنسيق الرد

ترجع واجهة برمجة التطبيقات كائن 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
  ]
}