リソースの検索

Cloud Asset API では、カスタムクエリ言語を使用して、プロジェクト、フォルダ、組織のリソース メタデータを検索できます。

始める前に

SearchAllResources を呼び出しています

gcloud

gcloud asset search-all-resources コマンドを使用して、SearchAllResources を呼び出すことができます。Cloud SDK バージョン 302.0.0 以降を実行する必要があります。gcloud version コマンドでバージョンを確認できます。

gcloud asset search-all-resources \
  --scope=SCOPE \
  --query=QUERY \
  --asset-types=ASSET_TYPES,… \
  --order-by=ORDER_BY \
  --page-size=PAGE_SIZE \

以下のフラグはすべて省略可能です。

  • (省略可)SCOPE: スコープはプロジェクト、フォルダ、または組織のいずれかになります。検索は、このスコープ内の Google Cloud リソースに制限されます。呼び出し元には、目的のスコープに対する cloudasset.assets.searchAllResources 権限を付与しておく必要があります。権限を指定しなかった場合、構成されたプロジェクト プロパティが使用されます。構成されたプロジェクトを探すには、gcloud config get-value project を実行します。設定を変更するには、gcloud config set project PROJECT_ID を実行します。

    使用できる値は次のとおりです。

    • projects/PROJECT_ID(例: 「projects/foo-bar」)
    • projects/PROJECT_NUMBER(例:「projects/12345678」)
    • folders/FOLDER_NUMBER(例:「folders/1234567」)
    • organizations/ORGANIZATION_NUMBER(例:「organizations/123456」)
  • (省略可)QUERY: クエリ ステートメント。詳細については、クエリの作成方法をご覧ください。指定されていない、または空の場合は、指定された scope 内のすべてのリソースが検索されます。

    例:

    • name:Important を使用して、名前に「Important」という単語が含まれている Google Cloud リソースを検索します。
    • name=Important を使用して、名前が「Important」である Google Cloud リソースを検索します。
    • displayName:Impor*: 表示名に単語の接頭辞として「Impor」を含む Google Cloud リソースを検索します。
    • location:us-west*: ロケーションに接頭辞として「us」と「west」の 2 単語が存在する Google Cloud リソースを検索します。
    • labels:prod: キーまたは値に「prod」という単語が含まれるラベルがある Google Cloud リソースを検索します。
    • labels.env:prod: キーが「env」、値に「prod」という単語が含まれる Google Cloud リソースを検索します。
    • labels.env:*: キーが「env」であるラベルがある Google Cloud リソースを検索します。
    • kmsKey:key: 名前に「key」という単語が含まれている、顧客管理の暗号鍵によって暗号化された Google Cloud リソースを検索します。
    • state:ACTIVE: 状態に「ACTIVE」という単語が含まれている Google Cloud リソースを検索します。
    • createTime<1609459200: 「2021-01-01 00:00:00 UTC」より前に作成された Google Cloud リソースを検索します。1609459200 は、「2021-01-01 00:00:00 UTC」のエポック タイムスタンプです(秒単位)。
    • updateTime>1609459200: 「2021-01-01 00:00:00 UTC」より後に更新された Google Cloud リソースを検索します。1609459200 は、「2021-01-01 00:00:00 UTC」のエポック タイムスタンプです(秒単位)。
    • Important: 検索可能なフィールドに「Important」という単語が含まれる Google Cloud リソースを検索します。
    • Impor*: 任意の検索フィールドに任意の単語の接頭辞として「Impor」を含む Google Cloud リソースを検索します。
    • Important location:(us-west1 OR global): 検索可能なフィールドに「Important」という単語が含まれ、かつ「us-west1」リージョンまたは「global」ロケーションにある Google Cloud リソースを検索します。
  • (省略可)ASSET_TYPES: 検索するアセットタイプの一覧。未指定または空の場合、すべての検索可能なアセットタイプが検索されます。例: プロジェクトと VM インスタンス リソースを検索する "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance"。正規表現もサポートされています。たとえば、"compute.googleapis.com.*" でアセットタイプが "compute.googleapis.com" で始まるリソースのスナップショットが作成されます。サポートされているすべての正規表現の構文については、RE2 をご覧ください。正規表現が、サポートされているアセットタイプと一致しない場合は、INVALID_ARGUMENT エラーが返されます。

  • (省略可)ORDER_BY: 結果の並べ替え順序を指定するフィールドのカンマ区切りリスト。デフォルトの順序は昇順です。降順を適用するには、フィールド名の後に " DESC" を追加します。重複したスペース文字は無視されます(例: "location DESC, name")。レスポンス内の文字列フィールド(namedisplayNamedescriptionlocation など)のみを並べ替えることができます。

  • (省略可)PAGE_SIZE: 検索結果ページを分割する際のページ数。最大値は 500 です。値が 0 に設定されている場合は、適切なデフォルト値が選択されます。

gcloud コマンドの例を以下に示します。

  • namemycompany という単語が含まれる organizations/123456 内のすべてのリソースを検索します。

    gcloud asset search-all-resources \
      --scope='organizations/123456'
      --query='name:mycompany'
    

api

プロジェクトで有効な OAuth トークンを使用して SearchAllResources を呼び出すことができます。Cloud Shell または gcloud コマンドを使用できるコンソールから SearchAllResources メソッドを呼び出すには、以下の手順に従います。

  1. プロジェクトの OAuth 同意画面を構成していない場合は、構成する必要があります。OAuth 同意画面には、メールアドレスとプロダクト名が必要です。

    1. プロジェクトの OAuth 同意画面に移動します。
      同意画面を構成
    2. [アプリケーション名] に、アプリケーションの表示名を入力します。
    3. [サポートメール] で、一般公開される連絡先として表示するメールアドレスを選択します。これは、自分のメールアドレスまたは自分が所有する Google グループである必要があります。
    4. 任意の詳細を追加します。
    5. [保存] をクリックします。
  2. プロジェクトの OAuth トークンを作成します。詳しくは、OAuth 2.0 の設定をご覧ください。

    1. OAuth クライアント ID の作成ページに移動します。
      OAuth クライアントの作成
    2. [デスクトップ アプリ] を [アプリケーションの種類] として選択します。
    3. [作成] をクリックします。
  3. client_secret.json ファイルをダウンロードします。

    1. [認証情報] ページに移動します。
    2. 新しい [クライアント ID] の右側にある [JSON をダウンロード] をクリックします。
    3. ご使用のアプリだけがアクセスできる場所に、ファイルを安全に保存します。
  4. 次のコマンドを使用して、JSON ファイルを使用してログインします。

    gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
    

    このコマンドを実行すると、リンクを開くよう求めるメッセージが表示されます。OAuth 同意画面で設定したアプリケーション名がページに表示されるかを確認します。

  5. 次のコマンドを使用して、アカウントの認証トークンを生成します。

    TOKEN=$(gcloud auth application-default print-access-token)
    
  6. curl コマンドを使用してリソースを検索できるようになりました。

    PAGE_SIZE=PAGE_SIZE
    PAGE_TOKEN="PAGE_TOKEN"
    SCOPE="SCOPE"
    QUERY="QUERY"
    ASSET_TYPES="ASSET_TYPES,…"
    ORDER_BY="ORDER_BY"
    curl -s -G \
       -H "Authorization: Bearer $TOKEN" \
       -d "page_size=$PAGE_SIZE" \
       -d "page_token=$PAGE_TOKEN" \
       -d "scope=$SCOPE" \
       -d "asset_types=$ASSET_TYPES" \
       -d "order_by=$ORDER_BY" \
       --data-urlencode "query=$QUERY" \
       "https://cloudasset.googleapis.com/v1/$SCOPE:searchAllResources"
    

以下のフラグはすべて省略可能です。

  • SCOPE は必須です。プロジェクト、フォルダ、組織がスコープになります。検索は、このスコープ内の Google Cloud リソースに制限されます。呼び出し元には、目的のスコープに対する cloudasset.assets.searchAllResources 権限を付与しておく必要があります。

    使用できる値は次のとおりです。

    • projects/PROJECT_ID(例: 「projects/foo-bar」)
    • projects/PROJECT_NUMBER(例:「projects/12345678」)
    • folders/FOLDER_NUMBER(例:「folders/1234567」)
    • organizations/ORGANIZATION_NUMBER(例:「organizations/123456」)
  • (省略可)QUERY: クエリ ステートメント。詳細については、クエリの作成方法をご覧ください。指定されていない、または空の場合は、指定された scope 内のすべてのリソースが検索されます。

    例:

    • name:Important を使用して、名前に「Important」という単語が含まれている Google Cloud リソースを検索します。
    • name=Important を使用して、名前が「Important」である Google Cloud リソースを検索します。
    • displayName:Impor*: 表示名に単語の接頭辞として「Impor」を含む Google Cloud リソースを検索します。
    • location:us-west*: ロケーションに接頭辞として「us」と「west」の両方が含まれる Google Cloud リソースを検索します。
    • labels:prod: キーまたは値に「prod」という単語が含まれるラベルがある Google Cloud リソースを検索します。
    • labels.env:prod: キーが「env」、値に「prod」という単語が含まれる Google Cloud リソースを検索します。
    • labels.env:*: キーが「env」であるラベルがある Google Cloud リソースを検索します。
    • kmsKey:key: 名前に「key」という単語が含まれている、顧客管理の暗号鍵によって暗号化された Google Cloud リソースを検索します。
    • state:ACTIVE: 状態に「ACTIVE」という単語が含まれている Google Cloud リソースを検索します。
    • createTime<1609459200: 「2021-01-01 00:00:00 UTC」より前に作成された Google Cloud リソースを検索します。1609459200 は、「2021-01-01 00:00:00 UTC」のエポック タイムスタンプです(秒単位)。
    • updateTime>1609459200: 「2021-01-01 00:00:00 UTC」より後に更新された Google Cloud リソースを検索します。1609459200 は、「2021-01-01 00:00:00 UTC」のエポック タイムスタンプです(秒単位)。
    • Important: 検索可能なフィールドに「Important」という単語が含まれる Google Cloud リソースを検索します。
    • Impor*: 任意の検索フィールドに任意の単語の接頭辞として「Impor」を含む Google Cloud リソースを検索します。
    • Important location:(us-west1 OR global): 検索可能なフィールドに「Important」という単語が含まれ、かつ「us-west1」リージョンまたは「global」ロケーションにある Google Cloud リソースを検索します。
  • (省略可)ASSET_TYPES: 検索するアセットタイプの一覧。未指定または空の場合、すべての検索可能なアセットタイプが検索されます。例: プロジェクトと VM インスタンス リソースを検索する "cloudresourcemanager.googleapis.com/Project,compute.googleapis.com/Instance"

  • (省略可)ORDER_BY: 結果の並べ替え順序を指定するフィールドのカンマ区切りリスト。デフォルトの順序は昇順です。降順を適用するには、フィールド名の後に " DESC" を追加します。重複したスペース文字は無視されます(例: "location DESC, name")。レスポンス内の文字列フィールド(namedisplayNamedescriptionlocation など)のみを並べ替えることができます。

  • (省略可)PAGE_SIZE: 検索結果ページを分割する際のページ数。最大値は 500 です。値が 0 に設定されている場合は、適切なデフォルト値が選択されます。

  • (省略可)PAGE_TOKEN: このメソッドに対する前の呼び出し結果の次のバッチを表すトークン。page_token は、前の呼び出しのレスポンスの next_page_token の値と同じである必要があります。

クライアント ライブラリと API リファレンス

クエリの作成方法

クエリ言語に関する詳細は、クエリ構文をご覧ください。

さまざまな実用例のサンプルクエリに関する詳細については、リソース サンプル の検索をご覧ください。

リソース メタデータ フィールドによる Google Cloud リソースの照会

リソース メタデータを検索するには、クエリ形式は次のようになります。

  • テキスト完全一致: FIELD=QUERY
  • テキスト部分一致: FIELD:QUERY
  • 数値一致: 比較演算子(=>>=<<=FIELDcomparison operatorQUERY

検索可能なリソース メタデータ FIELD は次のいずれかです。

  • name: リソースの完全なリソース名。注: すべてのアセットタイプが検索可能というわけではありません。検索可能なタイプのリストをご覧ください。
  • displayName: UI の表示名。
  • description: 1 つ以上の段落で表示されるリソースの説明テキスト。
  • location: リソースのロケーション。ロケーションは、「global」、「region」(「us-east1」など)、ゾーン(「us-west1-b」など)のいずれかです。
  • labels: このリソースに関連付けられたラベル。ラベルはラベルキー、ラベル値、またはその両方に一致します。GCP リソースのラベル付けとグループ化をご覧ください。

  • labels.[key]: このリソースに関連付けられたラベルキーによって識別されるラベル値(例: 「labels.env:prod」)。ラベルキーでは使用できるのは、ハイフン(-)、アンダースコア(_)、小文字、数字のみです。キーは小文字で始める必要があります。国際文字も使用できます。ラベルの要件をご覧ください。

  • networkTags: このリソースに関連付けられているネットワーク タグ。GCP リソースのラベル付けとグループ化をご覧ください。

  • kmsKey: このリソースの暗号化に使用される顧客管理の暗号鍵。CryptoKeyCryptoKeyVersion をご覧ください。

  • state: このリソースの状態のテキスト値。リソースタイプごとに、さまざまなリソースタイプのさまざまなフィールドからマップされるさまざまな状態定義があります。例: リソースが Compute Engine によって提供されるインスタンスである場合、その状態には、PROVISIONING、STAGING、RUNNING、STOPPING、SUSPENDING、SUSPENDED、REPAIRING、TERMINATED があります。API リファレンスstatus 定義をご覧ください。リソースが Cloud Resource Manager によって提供されるプロジェクトの場合、その状態には LIFECYCLE_STATE_UNSPECIFIED、ACTIVE、DELETE_REQUESTED、DELETE_IN_PROGRESS があります。API リファレンスlifecycleState の定義をご覧ください。

  • createTime: リソースが作成された時点を示す、このリソースの作成タイムスタンプ。精度は秒単位です。

  • updateTime: リソースの最終更新または削除が行われた時点を示す、このリソースの最終更新タイムスタンプ。精度は秒単位です。

例: 特定のフィールドによる照会

  • scope で、nameImportant という単語が含まれるすべてのリソースを検索します。

    name:Important
    
  • scope 内で、displayName に接頭辞 prod の付いた単語が含まれているすべてのリソースを検索します。

    displayName:prod*
    
  • scope で、locationus という単語が含まれるすべてのリソースを検索します。

    location:us
    
  • scopelocationus と完全に一致するすべてのリソースを検索します。

    location=us
    
  • キーまたは値のいずれかに prod という単語が含まれる label がある、scope 内のすべてのリソースを検索します。

    labels:prod
    
  • キーが env で値に prod という単語が含まれる label があるすべてのリソースを scope で検索します。

    labels.env:prod
    
  • キーが env で値が prod に完全に一致する label がある、scope 内のすべてのリソースを検索します。

    labels.env=prod
    
  • scope で、キーが envlabel があるすべてのリソースを検索します。

    labels.env:*
    
  • scope で、networkTagsinternal という単語が含まれているすべてのリソースを検索します。

    networkTags:internal
    
  • scope で、networkTagsinternal と完全に一致するリソースを探します。

    networkTags=internal
    
  • scope で、名前に key という単語が含まれている、顧客管理の暗号鍵で暗号化されたすべてのリソースを検索します。

    kmsKey:key
    
  • scope で、stateACTIVE という単語が含まれるすべてのリソースを検索します。

    state:ACTIVE
    
  • scope で、2021-01-01 00:00:00 UTC より前に作成されたすべてのリソースを検索します(1609459200 は、「2021-01-01 00:00:00 UTC」の秒単位のエポック タイムスタンプです)。

    createTime<1609459200
    
  • scope で、2021-01-01 00:00:00 UTC より後に更新されたすべてのリソースを検索します(1609459200 は、「2021-01-01 00:00:00 UTC」の秒単位のエポック タイムスタンプです)。

    updateTime>1609459200
    
  • scope で、nameImportant という単語、description に接頭辞 import の付いた単語を含むすべてのリソースを検索します。

    name:Important description:import*
    
  • scope で、nameImportant という単語、description が接頭辞 import の付いた単語を含むすべてのリソースを検索します。

    name:Important OR description:import*
    

フリーテキストによる Google Cloud リソースの照会

フィールドを指定せずに、フリーテキスト クエリだけを使用することもできます。クエリに一致するリソース メタデータにフィールドがある限り、リソースが返されます。

例: フリー テキストによる照会

  • scope 内でメタデータ フィールド(namedisplayNamedescription など)には、Important という単語が含まれています。

    Important
    
  • scope 内でメタデータ フィールド(namedisplayNamedescription など)に接頭辞 import の付いた単語を含むすべてのリソースを見つけます。

    import*
    
  • scope 内でメタデータ フィールド(namedisplayNamedescription など)に、Important という単語が含まれ、接頭辞 prod が付いた単語も含まれているリソースをすべて見つけます。

    Important prod*