API של מלאי ב- Power Platform

ה- API של המלאי מאפשר לך לבצע שאילתות מובנות מול Azure Resource Graph באמצעות בקשת POST עם מפרט שאילתה בגוף הבקשה. ה- API מתרגם את מפרט השאילתה שלך ל- Kusto Query Language (KQL) לביצוע מול Azure Resource Graph. ה- API של מלאי עבור משאבים הוא חלק מתיעוד ה- API של Power Platform. לקבלת רשימה מלאה של סוגי משאבים ושדות הניתנים לשאילתה, ראה חומר עזר לגבי סכימת מלאי של Power Platform.

אימות

ה- API של המלאי תומך כעת באימות משתמשים שהוקצה בלבד. קבל אסימון נושא עבור משתמש מחובר לפני שאתה מתקשר ל- API.

חשוב

ה- API אינו תומך באימות יישום בלבד באמצעות מנהל שירות או זהות מנוהלת. בקשות המשתמשות בזהויות אלה מחזירות HTTP 403 Forbidden.

לקבלת הוראות הגדרת אסימון, ראה אימות והשתמש בזרימת משתמש שהוקצתה. זרימת מנהל השירות המתוארת במאמר זה אינה חלה על ה- API של המלאי.

שימוש ב- Power Platform CLI (תצוגה מקדימה)

באפשרותך להפעיל שאילתות משאבי מלאי ממסוף באמצעות פקודת התצוגה המקדימה pac resource-query query-resources . הפקודה מקבלת את גוף הבקשה לשאילתה של JSON ישירות או מקובץ.

נקודת קצה של 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"
  }
}

מאפיינים

מאפיין‬	סוג	נדרש	Description
TableName	מחרוזת	‏‏כן‬	סוג הטבלה/המשאב המשמשים כיעד לשאילתה (כלומר, "PowerPlatformResources")
Clauses	מערך	‏‏כן‬	מערך של משפטי שאילתה המגדירים את הפעולות שיש לבצע
Options	אובייקט	לא	אפשרויות שאילתות ב-Azure Resource Graph עבור פגינה ושליטה בתוצאות

אפשרויות שאילתה

האובייקט Options תומך בפרמטרי שאילתה של Azure Resource Graph עבור פגינציה ושליטה בתוצאות. עיין ResourceQueryRequestOptions בתיעוד לקבלת מידע נוסף.

תנאים נתמכים לשאילתה

ה- API תומך בסוגי המשפטים המסומנים בסעיף זה באמצעות עריכה בסידרה פולימורית JSON. כל סוג משפט תואם לאופרטורים של KQL כפי שתועד בהפניית KQL:

משפט 'היכן'

סינון נתונים בהתבסס על תנאי שדה. מתרגם לאופרטור KQLwhere.

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

פסוקית פרויקט

בחירת שדות ספציפיים מהתוצאות. מתרגם לאופרטור 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"
}

סוגי צירוף נתמכים: ה- API תומך בכל סוגי הצירוף של KQL. לקבלת רשימה מלאה של סוגי צירוף זמינים והתנהגותם, עיין בתיעוד האופרטור KQL join.

דוגמה (צירוף משאבי 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'",
        "'microsoft.powerapps/apps'"
      ]
    },
    {
      "$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', 'microsoft.powerapps/apps')
| 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 אובייקט מ- SDK של Azure Resource Graph. אובייקט זה מכיל את תוצאות השאילתה ואת המטה-נתונים אודות ביצוע השאילתה.

מבנה תגובה:

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