resourcegraph.json

{
  "swagger": "2.0",
  "info": {
    "title": "Azure Resource Graph",
    "description": "Azure Resource Graph API Reference",
    "version": "2023-09-01-preview"
  },
  "host": "management.azure.com",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "security": [
    {
      "azure_auth": [
        "user_impersonation"
      ]
    }
  ],
  "securityDefinitions": {
    "azure_auth": {
      "type": "oauth2",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "flow": "implicit",
      "description": "Azure Active Directory OAuth2 Flow",
      "scopes": {
        "user_impersonation": "impersonate your user account"
      }
    }
  },
  "paths": {
    "/providers/Microsoft.ResourceGraph/resources": {
      "post": {
        "tags": [
          "Resources"
        ],
        "operationId": "Resources",
        "description": "Queries the resources managed by Azure Resource Manager for scopes specified in the request.",
        "externalDocs": {
          "description": "Learn more about the query syntax here",
          "url": "https://aka.ms/resource-graph/learntoquery"
        },
        "parameters": [
          {
            "$ref": "#/parameters/ApiVersionParameter"
          },
          {
            "name": "query",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/QueryRequest"
            },
            "description": "Request specifying query and its options."
          }
        ],
        "responses": {
          "200": {
            "description": "Result of the query operation",
            "schema": {
              "$ref": "#/definitions/QueryResponse"
            }
          },
          "default": {
            "description": "An error occurred while processing the request. See the error.code parameter to identify the specific error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Basic query": {
            "$ref": "./examples/ResourcesBasicQuery.json"
          },
          "Basic tenant query": {
            "$ref": "./examples/ResourcesTenantBasicQuery.json"
          },
          "Basic management group query": {
            "$ref": "./examples/ResourcesMgBasicQuery.json"
          },
          "Filter resources": {
            "$ref": "./examples/ResourcesFilterQuery.json"
          },
          "Summarize resources by location": {
            "$ref": "./examples/ResourcesSummarizeQuery.json"
          },
          "Complex query": {
            "$ref": "./examples/ResourcesComplexQuery.json"
          },
          "Access a properties field": {
            "$ref": "./examples/ResourcesPropertiesQuery.json"
          },
          "Query with a facet request": {
            "$ref": "./examples/ResourcesFacetQuery.json"
          },
          "First page query": {
            "$ref": "./examples/ResourcesFirstPageQuery.json"
          },
          "Next page query": {
            "$ref": "./examples/ResourcesNextPageQuery.json"
          },
          "Random page query": {
            "$ref": "./examples/ResourcesRandomPageQuery.json"
          }
        }
      }
    },
    "/providers/Microsoft.ResourceGraph/operations": {
      "get": {
        "tags": [
          "Operations"
        ],
        "description": "Lists all of the available REST API operations.",
        "operationId": "Operations_List",
        "x-ms-examples": {
          "OperationsList": {
            "$ref": "./examples/OperationsList.json"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/ApiVersionParameter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK. The request has succeeded.",
            "schema": {
              "$ref": "#/definitions/OperationListResult"
            }
          },
          "default": {
            "description": "An error occurred while processing the request. See the error.code parameter to identify the specific error.",
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-pageable": {
          "nextLinkName": null
        }
      }
    }
  },
  "definitions": {
    "QueryRequest": {
      "description": "Describes a query to be executed.",
      "type": "object",
      "properties": {
        "subscriptions": {
          "description": "Azure subscriptions against which to execute the query.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "Subscription Id."
          }
        },
        "managementGroups": {
          "description": "Azure management groups against which to execute the query. Example: [ 'mg1', 'mg2' ]",
          "type": "array",
          "items": {
            "type": "string",
            "description": "The name of Management group."
          }
        },
        "query": {
          "description": "The resources query.",
          "type": "string"
        },
        "options": {
          "description": "The query evaluation options",
          "$ref": "#/definitions/QueryRequestOptions"
        },
        "facets": {
          "description": "An array of facet requests to be computed against the query result.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/FacetRequest"
          }
        }
      },
      "required": [
        "query"
      ]
    },
    "QueryRequestOptions": {
      "description": "The options for query evaluation",
      "properties": {
        "$skipToken": {
          "description": "Continuation token for pagination, capturing the next page size and offset, as well as the context of the query.",
          "type": "string"
        },
        "$top": {
          "description": "The maximum number of rows that the query should return. Overrides the page size when ```$skipToken``` property is present.",
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 1000
        },
        "$skip": {
          "description": "The number of rows to skip from the beginning of the results. Overrides the next page offset when ```$skipToken``` property is present.",
          "type": "integer",
          "format": "int32",
          "minimum": 0
        },
        "resultFormat": {
          "description": "Defines in which format query result returned.",
          "type": "string",
          "enum": [
            "table",
            "objectArray"
          ],
          "default": "objectArray",
          "x-ms-enum": {
            "name": "ResultFormat",
            "modelAsString": false
          }
        },
        "allowPartialScopes": {
          "description": "Only applicable for tenant and management group level queries to decide whether to allow partial scopes for result in case the number of subscriptions exceed allowed limits.",
          "type": "boolean",
          "default": false
        },
        "authorizationScopeFilter": {
          "description": "Defines what level of authorization resources should be returned based on the which subscriptions and management groups are passed as scopes.",
          "type": "string",
          "enum": [
            "AtScopeAndBelow",
            "AtScopeAndAbove",
            "AtScopeExact",
            "AtScopeAboveAndBelow"
          ],
          "default": "AtScopeAndBelow",
          "x-ms-enum": {
            "name": "AuthorizationScopeFilter",
            "modelAsString": false
          }
        }
      }
    },
    "FacetRequest": {
      "description": "A request to compute additional statistics (facets) over the query results.",
      "type": "object",
      "properties": {
        "expression": {
          "description": "The column or list of columns to summarize by",
          "type": "string"
        },
        "options": {
          "description": "The options for facet evaluation",
          "$ref": "#/definitions/FacetRequestOptions"
        }
      },
      "required": [
        "expression"
      ]
    },
    "FacetRequestOptions": {
      "description": "The options for facet evaluation",
      "properties": {
        "sortBy": {
          "description": "The column name or query expression to sort on. Defaults to count if not present.",
          "type": "string"
        },
        "sortOrder": {
          "description": "The sorting order by the selected column (count by default).",
          "type": "string",
          "default": "desc",
          "enum": [
            "asc",
            "desc"
          ],
          "x-ms-enum": {
            "name": "FacetSortOrder",
            "modelAsString": false
          }
        },
        "filter": {
          "description": "Specifies the filter condition for the 'where' clause which will be run on main query's result, just before the actual faceting.",
          "type": "string"
        },
        "$top": {
          "description": "The maximum number of facet rows that should be returned.",
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 1000
        }
      }
    },
    "QueryResponse": {
      "description": "Query result.",
      "type": "object",
      "properties": {
        "totalRecords": {
          "description": "Number of total records matching the query.",
          "type": "integer",
          "format": "int64"
        },
        "count": {
          "description": "Number of records returned in the current response. In the case of paging, this is the number of records in the current page.",
          "type": "integer",
          "format": "int64"
        },
        "resultTruncated": {
          "description": "Indicates whether the query results are truncated.",
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-ms-enum": {
            "name": "ResultTruncated",
            "modelAsString": false
          }
        },
        "$skipToken": {
          "description": "When present, the value can be passed to a subsequent query call (together with the same query and scopes used in the current request) to retrieve the next page of data.",
          "type": "string"
        },
        "data": {
          "description": "Query output in JObject array or Table format.",
          "type": "object"
        },
        "facets": {
          "description": "Query facets.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Facet"
          }
        }
      },
      "required": [
        "totalRecords",
        "count",
        "resultTruncated",
        "data"
      ]
    },
    "Table": {
      "description": "Query output in tabular format.",
      "type": "object",
      "properties": {
        "columns": {
          "description": "Query result column descriptors.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Column",
            "description": "Column descriptor."
          }
        },
        "rows": {
          "description": "Query result rows.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Row",
            "description": "Query result row."
          }
        }
      },
      "required": [
        "columns",
        "rows"
      ]
    },
    "Column": {
      "description": "Query result column descriptor.",
      "type": "object",
      "properties": {
        "name": {
          "description": "Column name.",
          "type": "string"
        },
        "type": {
          "description": "Column data type.",
          "$ref": "#/definitions/ColumnDataType"
        }
      },
      "required": [
        "name",
        "type"
      ]
    },
    "ColumnDataType": {
      "description": "Data type of a column in a table.",
      "type": "string",
      "enum": [
        "string",
        "integer",
        "number",
        "boolean",
        "object",
        "datetime"
      ],
      "x-ms-enum": {
        "name": "ColumnDataType",
        "modelAsString": false
      }
    },
    "Row": {
      "description": "Query result row.",
      "type": "array",
      "items": {
        "type": "object",
        "description": "Cell value."
      }
    },
    "Facet": {
      "description": "A facet containing additional statistics on the response of a query. Can be either FacetResult or FacetError.",
      "type": "object",
      "properties": {
        "expression": {
          "description": "Facet expression, same as in the corresponding facet request.",
          "type": "string"
        },
        "resultType": {
          "description": "Result type",
          "type": "string"
        }
      },
      "required": [
        "expression",
        "resultType"
      ],
      "discriminator": "resultType"
    },
    "FacetResult": {
      "x-ms-discriminator-value": "FacetResult",
      "description": "Successfully executed facet containing additional statistics on the response of a query.",
      "type": "object",
      "properties": {
        "totalRecords": {
          "description": "Number of total records in the facet results.",
          "type": "integer",
          "format": "int64"
        },
        "count": {
          "description": "Number of records returned in the facet response.",
          "type": "integer",
          "format": "int32"
        },
        "data": {
          "description": "A JObject array or Table containing the desired facets. Only present if the facet is valid.",
          "type": "object"
        }
      },
      "required": [
        "totalRecords",
        "count",
        "data"
      ],
      "allOf": [
        {
          "$ref": "#/definitions/Facet"
        }
      ]
    },
    "FacetError": {
      "x-ms-discriminator-value": "FacetError",
      "description": "A facet whose execution resulted in an error.",
      "type": "object",
      "properties": {
        "errors": {
          "description": "An array containing detected facet errors with details.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/ErrorDetails"
          }
        }
      },
      "required": [
        "errors"
      ],
      "allOf": [
        {
          "$ref": "#/definitions/Facet"
        }
      ]
    },
    "ErrorResponse": {
      "title": "Error response.",
      "type": "object",
      "description": "An error response from the API.",
      "properties": {
        "error": {
          "$ref": "#/definitions/Error",
          "description": "Error information."
        }
      },
      "required": [
        "error"
      ]
    },
    "Error": {
      "title": "Error info.",
      "type": "object",
      "description": "Error details.",
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code identifying the specific error."
        },
        "message": {
          "type": "string",
          "description": "A human readable error message."
        },
        "details": {
          "type": "array",
          "description": "Error details",
          "items": {
            "$ref": "#/definitions/ErrorDetails"
          }
        }
      },
      "required": [
        "code",
        "message"
      ]
    },
    "ErrorDetails": {
      "title": "Error details.",
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code identifying the specific error."
        },
        "message": {
          "type": "string",
          "description": "A human readable error message."
        }
      },
      "additionalProperties": {
        "type": "object"
      },
      "required": [
        "code",
        "message"
      ]
    },
    "OperationListResult": {
      "description": "Result of the request to list Resource Graph operations. It contains a list of operations and a URL link to get the next set of results.",
      "properties": {
        "value": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Operation"
          },
          "description": "List of Resource Graph operations supported by the Resource Graph resource provider."
        }
      }
    },
    "Operation": {
      "description": "Resource Graph REST API operation definition.",
      "properties": {
        "name": {
          "description": "Operation name: {provider}/{resource}/{operation}",
          "type": "string"
        },
        "display": {
          "description": "Display metadata associated with the operation.",
          "properties": {
            "provider": {
              "description": "Service provider: Microsoft Resource Graph.",
              "type": "string"
            },
            "resource": {
              "description": "Resource on which the operation is performed etc.",
              "type": "string"
            },
            "operation": {
              "description": "Type of operation: get, read, delete, etc.",
              "type": "string"
            },
            "description": {
              "description": "Description for the operation.",
              "type": "string"
            }
          }
        },
        "origin": {
          "type": "string",
          "description": "The origin of operations."
        }
      }
    }
  },
  "parameters": {
    "ApiVersionParameter": {
      "name": "api-version",
      "in": "query",
      "required": true,
      "type": "string",
      "description": "Api Version."
    }
  }
}