保存したクエリを管理

このページでは、保存した Policy Analyzer のクエリを作成、管理、実行する方法を説明します。1 つのアセットには最大 200 個の保存したクエリを作成できます。この上限には、その子の保存したクエリは含まれません。たとえば、ある組織に 10 個のプロジェクトがある場合、各プロジェクトは最大 200 個の保存したクエリを持ち、組織は最大 200 個の保存したクエリを持つことができます。

始める前に

  1. Cloud Asset API を有効にします。

    API を有効にする

必要なロール

保存されたクエリを作成および管理するために必要な権限を取得するには、クエリの保存先となるプロジェクト、フォルダ、または組織に対するCloud Asset オーナー(roles/cloudasset.owner)のIAM ロールの付与を管理者に依頼します。ロールの付与の詳細については、アクセスの管理をご覧ください。

この事前定義ロールには、保存クエリの作成と管理に必要な権限が含まれています。必要な権限を正確に確認するには、[必要な権限] セクションを開いてください。

必要な権限

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

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

保存するクエリを作成

親プロジェクト、フォルダ、または組織に、保存した Policy Analyzer クエリを作成するには、Cloud Asset Inventory API の savedQueries.create メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: クエリを保存するリソースタイプ。 値 projectsfolders、または organizations を使用します。
  • RESOURCE_ID: クエリを保存する Google Cloud プロジェクト、フォルダ、または組織の ID。プロジェクト ID は英数字または数値を使用できます。フォルダ ID と組織 ID は数値です。
  • QUERY_ID: 保存したクエリに使用する ID。指定した親リソース(プロジェクト、フォルダ、組織)内で一意にする必要があります。クエリ ID には、文字、数字、ハイフンを使用できます。
  • SCOPE_RESOURCE_TYPE: 検索の対象範囲のリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 projectsfolders、または organizations を使用します。
  • SCOPE_RESOURCE_ID: 検索の対象範囲の Google Cloud プロジェクト、フォルダ、または組織の ID。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • FULL_RESOURCE_NAME: 省略可。アクセスを分析するリソースの完全なリソース名。完全なリソース名の形式の一覧については、リソース名の形式をご覧ください。
  • PRINCIPAL: 省略可。アクセスを分析するプリンシパル。PRINCIPAL_TYPE:ID の形式。(例: user:my-user@example.com)プリンシパル タイプの完全なリストについては、プリンシパル識別子をご覧ください。
  • PERMISSION_1PERMISSION_2、...PERMISSION_N:省略可。確認する権限(compute.instances.get など)。複数の権限を一覧表示すると、Policy Analyzer はリストされた権限を確認します。
  • LABEL_KEYLABEL_VALUE: クエリに関連付ける Key-Value ペア。検索と一覧表示のオペレーションで使用できます。保存したクエリごとに最大 10 個のラベルを含めることができます。
  • DESCRIPTION: クエリを記述する文字列。

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスに、保存したクエリが含まれます。たとえば、次のようになります。

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

保存したクエリを実行する

保存した分析クエリを実行するには、Cloud Asset Inventory API の analyzeIamPolicy メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • SCOPE_RESOURCE_TYPE: 検索の対象範囲のリソースのタイプ。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。値 projectsfolders、または organizations を使用します。
  • SCOPE_RESOURCE_ID: 検索の対象範囲の Google Cloud プロジェクト、フォルダ、または組織の ID。このリソースとその子孫に添付された IAM 許可ポリシーのみが分析されます。プロジェクト ID は英数字からなる文字列です(例: my-project)。フォルダ ID と組織 ID は数値です(例: 123456789012)。
  • RESOURCE_TYPE: クエリが保存されているリソースタイプ。値 projectsfolders、または organizations を使用します。
  • RESOURCE_NUM_ID: クエリが保存されている Google Cloud プロジェクト、フォルダ、または組織の数値 ID。英数字のプロジェクト ID を使用してプロジェクトを識別することはできません。プロジェクト番号を使用する必要があります。
  • QUERY_ID: 使用する保存したクエリの ID。

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、指定されたリソースに対して保存したクエリを実行した結果が含まれます。クエリ結果の例については、IAM ポリシーの分析をご覧ください。

保存したクエリを取得する

保存された Policy Analyzer クエリを取得するには、Cloud Asset Inventory API の savedQueries.get メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: クエリが保存されているリソースタイプ。値 projectsfolders、または organizations を使用します。
  • RESOURCE_NUM_ID: クエリが保存されている Google Cloud プロジェクト、フォルダ、または組織の数値 ID。英数字のプロジェクト ID を使用してプロジェクトを識別することはできません。プロジェクト番号を使用する必要があります。
  • QUERY_ID: 取得する保存済みクエリの ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスに、保存したクエリが含まれます。たとえば、次のようになります。

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

保存したクエリの一覧を表示

プロジェクト、フォルダ、または組織に保存されているすべての Policy Analyzer クエリを一覧表示するには、Cloud Asset Inventory API の savedQueries.list メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: クエリが保存されるリソースタイプ。 値 projectsfolders、または organizations を使用します。
  • RESOURCE_ID: クエリを保存する Google Cloud プロジェクト、フォルダ、または組織の ID。プロジェクト ID は英数字または数値を使用できます。フォルダ ID と組織 ID は数値です。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、プロジェクト、フォルダ、または組織に対する保存された Policy Analyzer クエリがすべて含まれます。 たとえば、次のようになります。

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

保存したクエリの更新

保存された Policy Analyzer クエリを更新するには、Cloud Asset Inventory API の savedQueries.patch メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: クエリが保存されているリソースタイプ。値 projectsfolders、または organizations を使用します。
  • RESOURCE_NUM_ID: クエリが保存されている Google Cloud プロジェクト、フォルダ、または組織の数値 ID。英数字のプロジェクト ID を使用してプロジェクトを識別することはできません。プロジェクト番号を使用する必要があります。
  • QUERY_ID: 編集する保存したクエリの ID。
  • UPDATED_FIELDS: 更新するフィールドのカンマ区切りリスト。たとえば、コンテンツ、ラベル、説明のフィールドを更新する場合は、値 content,labels,description を使用します。
  • UPDATED_QUERY: 省略可。保存する、更新された Policy Analyzer のクエリ。クエリのフォーマット方法については、保存クエリの作成をご覧ください。
  • UPDATED_LABELS: 省略可。保存クエリに付ける更新後のラベル。
  • UPDATED_DESCRIPTION: 省略可。保存されたクエリの更新された説明。

HTTP メソッドと URL:

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

JSON 本文のリクエスト:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

レスポンスには、更新されたクエリが含まれます。

保存したクエリを削除する

保存された Policy Analyzer クエリを削除するには、Cloud Asset Inventory API の savedQueries.delete メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RESOURCE_TYPE: クエリが保存されているリソースタイプ。値 projectsfolders、または organizations を使用します。
  • RESOURCE_NUM_ID: クエリが保存されている Google Cloud プロジェクト、フォルダ、または組織の数値 ID。英数字のプロジェクト ID を使用してプロジェクトを識別することはできません。プロジェクト番号を使用する必要があります。
  • QUERY_ID: 削除する保存済みクエリの ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

クエリが正常に削除されると、API は空のレスポンスを返します。