Manage saved queries

Stay organized with collections Save and categorize content based on your preferences.

This page shows you how to create, manage, and run saved Policy Analyzer queries. You can create up to 200 saved queries on an asset. This limit does not include the saved queries of its children. For example, if you have 10 projects under an organization, each project can have up to 200 saved queries and the organization can have up to 200 saved queries.

Before you begin

  1. Enable the Cloud Asset API.

    Enable the API

Required roles

To get the permissions that you need to create and manage saved queries, ask your administrator to grant you the Cloud Asset Owner (roles/cloudasset.owner) IAM role on the project, folder, or organization that you will save your query to. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to create and manage saved queries. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

  • cloudasset.savedqueries.create
  • cloudasset.savedqueries.delete
  • cloudasset.savedqueries.get
  • cloudasset.savedqueries.list
  • cloudasset.savedqueries.update

You might also be able to get these permissions with custom roles or other predefined roles.

Create a saved query

To creates a saved Policy Analyzer query in a parent project, folder, or organization, use the Cloud Asset Inventory API's savedQueries.create method.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The resource type that you want to save a query for. Use the value projects, folders, or organizations.
  • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to save a query for. Project IDs can be alphanumeric or numeric. Folder and organization IDs are numeric.
  • QUERY_ID: The ID to use for the saved query, which must be unique in the specified parent resource (project, folder, or organization). You can use letters, numbers, and hyphens in the query ID.
  • SCOPE_RESOURCE_TYPE: The type of the resource that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Use the value projects, folders, or organizations.
  • SCOPE_RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • FULL_RESOURCE_NAME: Optional. The full resource name of the resource that you want to analyze access for. For a list of full resource name formats, see Resource name format.
  • PRINCIPAL: Optional. The principal whose access you want to analyze, in the form PRINCIPAL_TYPE:ID—for example, user:my-user@example.com. For a full list of the principal types, see Principal identifiers.
  • PERMISSION_1, PERMISSION_2... PERMISSION_N: Optional. The permissions that you want to check for—for example, compute.instances.get. If you list multiple permissions, Policy Analyzer will check for any of the permissions listed.
  • LABEL_KEY and LABEL_VALUE: A key/value pair to attach to the query, which can be used in search and list operations. You can include up to 10 labels for each saved query.
  • DESCRIPTION: A string describing the query.

HTTP method and URL:

POST https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/savedQueries?savedQueryId=QUERY_ID

Request JSON body:

{
  "content": {
    "iamPolicyAnalysisQuery": {
      "scope": "SCOPE_RESOURCE_TYPE/SCOPE_RESOURCE_ID"
      "resourceSelector": {
        "fullResourceName": "FULL_RESOURCE_NAME"
      },
      "identitySelector": {
        "identity": "PRINCIPAL"
      },
      "accessSelector": {
        "permissions": [
          "PERMISSION_1",
          "PERMISSION_2",
          "PERMISSION_N"
        ]
      }
    }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
  "description": "DESCRIPTION"
}

To send your request, expand one of these options:

The response contains the saved query. For example, it might look like the following:

{
  "name": "projects/12345678901/savedQueries/my-query",
  "description": "A query checking what permissions my-user@example.com has on my-project",
  "createTime": "2022-04-18T22:47:25.640783Z",
  "lastUpdateTime": "2022-04-18T22:47:25.640783Z",
  "labels": {
    "user": "my-user"
  },
  "content": {
    "iamPolicyAnalysisQuery": {
      "scope": "projects/scope-project",
      "resourceSelector": {
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project"
      },
      "identitySelector": {
        "identity": "user:my-user@example.com"
      }
    }
  }
}

Run a saved query

To run a saved analysis query, use the Cloud Asset Inventory API's analyzeIamPolicy method.

Before using any of the request data, make the following replacements:

  • SCOPE_RESOURCE_TYPE: The type of the resource that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Use the value projects, folders, or organizations.
  • SCOPE_RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
  • RESOURCE_TYPE: The resource type where the query is saved. Use the value projects, folders, or organizations.
  • RESOURCE_NUM_ID: The numeric ID of the Google Cloud project, folder, or organization where the query is saved. You can't use the alphanumeric project ID to identify a project—you must use the project number.
  • QUERY_ID: The ID of the saved query that you want to use.

HTTP method and URL:

POST https://cloudasset.googleapis.com/v1/SCOPE_RESOURCE_TYPE/SCOPE_RESOURCE_ID:analyzeIamPolicy

Request JSON body:

{
  "savedAnalysisQuery": "RESOURCE_TYPE/RESOURCE_NUM_ID/savedQueries/QUERY_ID"
}

To send your request, expand one of these options:

The response contains the results of running the saved query on the specified resource. For examples of query results, see Analyze IAM policies.

Get a saved query

To gets a saved Policy Analyzer query, use the Cloud Asset Inventory API's savedQueries.get method.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The resource type where the query is saved. Use the value projects, folders, or organizations.
  • RESOURCE_NUM_ID: The numeric ID of the Google Cloud project, folder, or organization where the query is saved. You can't use the alphanumeric project ID to identify a project—you must use the project number.
  • QUERY_ID: The ID of the saved query that you want to get.

HTTP method and URL:

GET https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUM_ID/savedQueries/QUERY_ID

To send your request, expand one of these options:

The response contains the saved query. For example, it might look like the following:

{
  "name": "projects/12345678901/savedQueries/my-query",
  "description": "A query checking what permissions my-user@example.com has on my-project",
  "createTime": "2022-04-18T22:47:25.640783Z",
  "lastUpdateTime": "2022-04-18T22:47:25.640783Z",
  "labels": {
    "user": "my-user"
  },
  "content": {
    "iamPolicyAnalysisQuery": {
      "scope": "projects/scope-project",
      "resourceSelector": {
        "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project"
      },
      "identitySelector": {
        "identity": "user:my-user@example.com"
      }
    }
  }
}

List saved queries

To lists all saved Policy Analyzer queries in a project, folder, or organization, use the Cloud Asset Inventory API's savedQueries.list method.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The resource type where the queries are saved. Use the value projects, folders, or organizations.
  • RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to save a query for. Project IDs can be alphanumeric or numeric. Folder and organization IDs are numeric.

HTTP method and URL:

GET https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/savedQueries

To send your request, expand one of these options:

The response contains all saved Policy Analyzer queries for the project, folder, or organization. For example, it might look like the following:

{
  "savedQueries": [
    {
      "name": "projects/12345678901/savedQueries/query-1",
      "description": "A query checking what permissions my-user@example.com has on my-project",
      "createTime": "2022-04-15T21:17:33.777212Z",
      "lastUpdateTime": "2022-04-15T21:17:33.777212Z",
      "labels": {
        "missing-info": "permission"
      },
      "content": {
        "iamPolicyAnalysisQuery": {
          "scope": "projects/scope-project",
          "resourceSelector": {
            "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project"
          },
          "identitySelector": {
            "identity": "user:my-user@example.com"
          }
        }
      }
    },
    {
      "name": "projects/12345678901/savedQueries/query-2",
      "description": "A query checking what resources my-user@example.com has permission to view roles on",
      "createTime": "2022-04-18T22:47:25.640783Z",
      "lastUpdateTime": "2022-04-18T22:47:25.640783Z",
      "labels": {
        "missing-info": "resource"
      },
      "content": {
        "iamPolicyAnalysisQuery": {
          "scope": "projects/scope-project",
          "accessSelector": {
            "permissions": [
              "iam.roles.get",
              "iam.roles.list"
            ]
          },
          "identitySelector": {
            "identity": "user:my-user@example.com"
          }
        }
      }
    }
  ]
}

Update a saved query

To updates a saved Policy Analyzer query, use the Cloud Asset Inventory API's savedQueries.patch method.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The resource type where the query is saved. Use the value projects, folders, or organizations.
  • RESOURCE_NUM_ID: The numeric ID of the Google Cloud project, folder, or organization where the query is saved. You can't use the alphanumeric project ID to identify a project—you must use the project number.
  • QUERY_ID: The ID of the saved query that you want to edit.
  • UPDATED_FIELDS: A comma-separated lists of the fields that you want to update. For example, if you are updating the content, labels, and description fields, you would use the value content,labels,description.
  • UPDATED_QUERY: Optional. The updated Policy Analyzer query that you want to save. To learn how to format the query, see Create a saved query.
  • UPDATED_LABELS: Optional. The updated labels that you want to attach to the saved query.
  • UPDATED_DESCRIPTION: Optional. An updated description for the saved query.

HTTP method and URL:

POST https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUM_ID/savedQueries/QUERY_ID?update_mask=UPDATED_FIELDS

Request JSON body:

{
  "content": {
    "iamPolicyAnalysisQuery": {
      UPDATED_QUERY
  },
  "labels": {
    UPDATED_LABELS
  },
  "description": "UPDATED_DESCRIPTION"
}

To send your request, expand one of these options:

The response contains the updated query.

Delete a saved query

To deletes a saved Policy Analyzer query, use the Cloud Asset Inventory API's savedQueries.delete method.

Before using any of the request data, make the following replacements:

  • RESOURCE_TYPE: The resource type where the query is saved. Use the value projects, folders, or organizations.
  • RESOURCE_NUM_ID: The numeric ID of the Google Cloud project, folder, or organization where the query is saved. You can't use the alphanumeric project ID to identify a project—you must use the project number.
  • QUERY_ID: The ID of the saved query that you want to delete.

HTTP method and URL:

DELETE https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUM_ID/savedQueries/QUERY_ID

To send your request, expand one of these options:

If the query is successfully deleted, the API returns an empty response.