VM メタデータの表示とクエリ

Linux Windows

---

すべての仮想マシン（VM）は、メタデータをメタデータ サーバーのディレクトリに保存します。VM からこのメタデータ サーバーの API にアクセスするのに追加の承認は必要ありません。自動的にアクセスできるようになります。このドキュメントの次のセクションで説明するメソッドを使用して、VM メタデータ値を表示してクエリを実行できます。

• VM 内からメタデータに対してプログラムでクエリを実行する
• VM のカスタム メタデータを表示する

メタデータ サーバーにアクセスするときにエラーが発生した場合は、メタデータ サーバーへのアクセスに関する問題のトラブルシューティングをご覧ください。

上級者向けのヒント: メンテナンス イベントにより、メタデータ サーバーの利用可能状態が最大 1 秒中断されることがあります。このとき、メタデータ サーバーは Error 503 HTTP サーバー レスポンスを返すことがあります。アプリケーションをメンテナンス イベントに耐えられるようにするには、メタデータ サーバーをクエリするアプリケーションに再試行ロジックを実装することをおすすめします。

始める前に

• Windows Server VM の場合は、PowerShell 3.0 以降を使用します。コピーしたコードブロックを貼り付ける場合は ctrl+v の使用をおすすめします。
• Compute Engine の VM メタデータを定義、分類、配置する方法の基本を確認します。詳細については、VM メタデータについてをご覧ください。
• まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように Compute Engine に対する認証を行います。
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  Python

  ローカル開発環境でこのページの Python サンプルを使用するには、gcloud CLI をインストールして初期化し、ユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定します。

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  詳細については Set up authentication for a local development environment をご覧ください。

  REST

  このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  詳細については、Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

必要なロール

Google Cloud コンソール、Google Cloud CLI、または REST を使用して VM の外部からカスタム メタデータを表示するには、次のロールと権限が必要です。VM 内からメタデータをプログラムでクエリする場合は、VM に接続するためのロールと権限のみが必要です。

VM の外部からカスタム メタデータを表示するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• VM またはプロジェクトに対する Compute インスタンス管理者（v1）（roles/compute.instanceAdmin.v1）
• VM でサービス アカウントを使用する場合: サービス アカウントまたはプロジェクトに対するサービス アカウント ユーザー（roles/iam.serviceAccountUser）

ロールの付与の詳細については、アクセスの管理をご覧ください。

これらの事前定義ロールには、VM の外部からカスタム メタデータを表示するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

VM の外部からカスタム メタデータを表示するには、次の権限が必要です。

• プロジェクトのカスタム メタデータを表示する: プロジェクトに対する compute.projects.get
• カスタム ゾーン メタデータを表示する: プロジェクトの必要なゾーンのインスタンス設定に対する compute.instanceSettings.get
• VM インスタンスのカスタム メタデータを表示する: VM に対する compute.instances.get
• VM でサービス アカウントを使用する場合: サービス アカウントまたはプロジェクトに対する iam.serviceAccounts.actAs

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

プログラムによるメタデータのクエリ

Linux または Windows の VM 内からメタデータ値のエントリをクエリすることで、すべてのメタデータにアクセスできます。VM 内からプログラムでメタデータ値をクエリするには、次のいずれかの方法を使用します（Linux の場合は curl ツール、Windows の場合は Invoke-RestMethod などのツールを使用します）。

• 単一のメタデータ エントリに対してクエリを実行する
• メタデータ ディレクトリのリストに対してクエリを実行する
• wait-for-change 機能を使用してメタデータの変更をクエリする

メタデータ サーバー エンドポイント

VM 内からプログラムでメタデータをクエリするには、次のメタデータ サーバー エンドポイントを使用します。

• どの VM でも、http エンドポイント（http://metadata.google.internal/computeMetadata/v1）を使用してメタデータ サーバーにクエリを実行できます。

• Shielded VM の場合は、次のいずれかを使用してメタデータ サーバーにクエリを実行できます。

  • http エンドポイント: http://metadata.google.internal/computeMetadata/v1
  • https エンドポイント: https://metadata.google.internal/computeMetadata/v1。この https エンドポイントはプレビュー版で利用できます。https エンドポイントをクエリする形式については、HTTPS メタデータ サーバー エンドポイントを使用してメタデータをクエリするをご覧ください。

このドキュメントのほとんどの例では、http エンドポイントを使用しています。ただし、https エンドポイントと http エンドポイントのどちらを使用しても、同じメタデータ エントリにアクセスできます。

メタデータ リクエストの部分

次の表に、メタデータ クエリ リクエストの主要部分を示します。

コンポーネント	説明
ルート URL	すべてのメタデータ値は、次のルート URL のサブパスとして定義されます。 http エンドポイント: http://metadata.google.internal/computeMetadata/v1 http://169.254.169.254/computeMetadata/v1 http://metadata.goog/computeMetadata/v1 https エンドポイント（プレビュー）: https://metadata.google.internal/computeMetadata/v1 プレビュー ステージでは、この URL のみがサポートされます。
リクエスト ヘッダー	このヘッダーにより、そのリクエストがメタデータ値を取得する目的で送信されたものであり、安全でないソースから意図せず送信されたものではないことが示されるため、リクエストしたデータがメタデータ サーバーから返されるようになります。このヘッダーが含まれていないリクエストはメタデータ サーバーで拒否されます。 Metadata-Flavor: Google 注: 以前は、リクエストに X-Google-Metadata-Request: True ヘッダーが含まれている必要がありました。どちらのヘッダーもまだサポートされていますが、X-Google-Metadata-Request: True ヘッダーではなく Metadata-Flavor ヘッダーを使用することをおすすめします。

単一のメタデータ エントリに対してクエリを実行する

次のコマンドを使用して、単一のメタデータ エントリをクエリします。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリをクエリするには、次のコマンドを実行します。

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   たとえば、VM のブートイメージにクエリを実行するには、次のクエリを実行します。

   user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/image" -H "Metadata-Flavor: Google"
   

   出力は次のようになります。

   projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

1. Windows VM に接続します。

2. Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリをクエリするには、次のコマンドを実行します。

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
   $value
   

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   たとえば、VM のブートイメージにクエリを実行するには、次のクエリを実行します。

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image")
   $value
   

   出力は次のようになります。

   projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

メタデータのディレクトリ リスティングをクエリする

メタデータのディレクトリ リスティングに対してクエリを実行するには、次のコマンドを使用します。ディレクトリ リスティングは、他のメタデータキーを含むメタデータ エントリです。末尾にスラッシュが付いているメタデータ エントリがディレクトリ リスティングです。

Linux

1. Linux VM に接続します。

2. Linux VM から VM インスタンスまたはプロジェクトのメタデータ ディレクトリをクエリするには、次のコマンドを実行します。

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/" -H "Metadata-Flavor: Google"
     

   PATH_TO_METADATA_DIRECTORY は、リスティングを再帰的にクエリする VM インスタンスまたはプロジェクトのメタデータ ディレクトリのパスに置き換えます。次に例を示します。

   • attributes プロジェクト メタデータ ディレクトリ エントリを表示するには、project/attributes/ のパスを指定します。
   • disks VM インスタンスのメタデータ ディレクトリ エントリを表示するには、instance/disks/ のパスを指定します。

   たとえば、VM にアタッチされているディスクのディレクトリである disks/ エントリについて考えてみましょう。disks/ エントリをクエリするには、次の手順を完了します。

   1. ディスク ディレクトリで curl ツールコマンドを実行します。

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
      

      出力は次のようになります。

      0/
      1/
      2/
      

   2. ディスクの 0/ ディレクトリに関する詳細情報が必要な場合は、そのディレクトリの特定の URL をクエリで取得できます。

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"
      

      出力は次のようになります。

      device-name
      index
      mode
      type
      

   3. 次に、ディスク 0/ のディスクタイプ（type）をクエリするために、次のコマンドを実行します。

      user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type" -H "Metadata-Flavor: Google"
      

      出力は次のようになります。

      PERSISTENT
      

Windows

disks/ というエントリは、その VM にアタッチされているディスクのディレクトリです。ディスク エントリをクエリするには、次の手順を完了します。

1. Windows VM に接続します。

2. Windows VM から VM インスタンスまたはプロジェクトのメタデータ ディレクトリをクエリするには、次のコマンドを実行します。

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/")
   $value
   

   PATH_TO_METADATA_DIRECTORY は、リスティングを再帰的にクエリする VM インスタンスまたはプロジェクトのメタデータ ディレクトリのパスに置き換えます。次に例を示します。

   • attributes プロジェクト メタデータ ディレクトリ エントリを表示するには、project/attributes/ のパスを指定します。
   • disks VM インスタンスのメタデータ ディレクトリ エントリを表示するには、instance/disks/ のパスを指定します。

   たとえば、VM にアタッチされているディスクのディレクトリである disks/ エントリについて考えてみましょう。disks/ エントリをクエリするには、次の手順を完了します。

   1. ディスク ディレクトリで Invoke-RestMethod コマンドを実行します。

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/")
      $value
      

      出力は次のようになります。

      0/
      1/
      2/
      

   2. ディスク 0/ ディレクトリに関する詳細情報が必要な場合は、そのディレクトリの特定の URL をクエリで取得できます。

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/")
      $value
      

      出力は次のようになります。

      device-name
      index
      mode
      type
      

   3. 次に、ディスク 0/ のディスクタイプ（type）をクエリするために、次のコマンドを実行します。

      PS C:\> 
      $value = (Invoke-RestMethod `
                -Headers @{'Metadata-Flavor' = 'Google'} `
                -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type")
      $value
      

      出力は次のようになります。

      PERSISTENT
      

ディレクトリ リスティングを再帰的にクエリする

ディレクトリ以下のすべての内容が返されるようにするには、リクエストで recursive=true クエリ パラメータを使用します。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ ディレクトリのリスティングを再帰的にクエリするには、次のコマンドを実行します。

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_DIRECTORY は、リスティングを再帰的にクエリする VM インスタンスまたはプロジェクトのメタデータ ディレクトリのパスに置き換えます。次に例を示します。

   • attributes プロジェクト メタデータ ディレクトリ エントリを表示するには、project/attributes/ のパスを指定します。
   • disks VM インスタンスのメタデータ ディレクトリ エントリを表示するには、instance/disks/ のパスを指定します。

   たとえば、次のコマンドを実行すると、disks/ ディレクトリのインスタンス メタデータ リスティングを再帰的にクエリします。

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"
     

   出力は次のようになります。

     [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
     {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
     

   デフォルトでは、再帰クエリの結果は JSON 形式で返されます。これらの内容をテキスト形式で返されるようにするには、alt=text クエリ パラメータを追加します。

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"
     

   出力は次のようになります。

     0/device-name boot
     0/index 0
     0/mode READ_WRITE
     0/type PERSISTENT
     1/device-name persistent-disk-1
     1/index 1
     1/mode READ_WRITE
     1/type PERSISTENT
     2/device-name persistent-disk-1
     2/index 2
     2/mode READ_ONLY
     2/type PERSISTENT
     

Windows

1. Windows VM に接続します。

2. Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ ディレクトリのリスティングを再帰的にクエリするには、次のコマンドを実行します。

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true")
     $value
     

   PATH_TO_METADATA_DIRECTORY は、リスティングを再帰的にクエリする VM インスタンスまたはプロジェクトのメタデータ ディレクトリのパスに置き換えます。次に例を示します。

   • attributes プロジェクト メタデータ ディレクトリ エントリを表示するには、project/attributes/ のパスを指定します。
   • disks VM インスタンスのメタデータ ディレクトリ エントリを表示するには、instance/disks/ のパスを指定します。

   たとえば、次のコマンドを実行すると、disks/ ディレクトリのインスタンス メタデータ リスティングを再帰的にクエリします。

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true")
   $value
   

   出力は次のようになります。

   [{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
   {"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]
   

   デフォルトでは、再帰クエリの結果は JSON 形式で返されます。これらの内容をテキスト形式で返されるようにするには、alt=text クエリ パラメータを追加します。

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
   $value
   

   出力は次のようになります。

   0/device-name boot
   0/index 0
   0/mode READ_WRITE
   0/type PERSISTENT
   1/device-name persistent-disk-1
   1/index 1
   1/mode READ_WRITE
   1/type PERSISTENT
   2/device-name persistent-disk-1
   2/index 2
   2/mode READ_ONLY
   2/type PERSISTENT
   

クエリ出力を書式設定する

デフォルトでは、エンドポイントごとにレスポンスの形式があらかじめ定義されています。データを JSON 形式で返すエンドポイントもあれば、文字列として返すエンドポイントもあります。指定されているデフォルトのデータ形式をオーバーライドするには、クエリ パラメータの alt=json（データを JSON 文字列形式で返す）または alt=text（データの平文表現を返す）を使用します。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリのクエリ レスポンス データ形式を変更するには、次のコマンドを実行します。

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
   

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • DATA_FORMAT: クエリ レスポンス データ形式（例: text、json）。

例

たとえば、tags キーではデータが自動的に JSON 形式で返されますが、これをテキスト形式で返されるように変更するには、alt=text クエリ パラメータを指定します。

デフォルトのキーワード

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
  

出力は次のようになります。

  ["http-server", "db-client", "app-server", "mysql-server"]
  

書式設定を使用したクエリ

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"
  

出力は次のようになります。

  http-server
  db-client
  app-server
  mysql-server

Windows

1. Windows VM に接続します。

2. Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリのクエリ レスポンス データ形式を変更するには、次のコマンドを実行します。

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT")
     $value
     

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • DATA_FORMAT: クエリ レスポンス データ形式（例: text、json）。

例

たとえば、tags キーではデータが自動的に JSON 形式で返されますが、これをテキスト形式で返されるように変更するには、alt=text クエリ パラメータを指定します。

デフォルトのキーワード

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
  $value
  

出力は次のようになります。

  ["http-server", "db-client", "app-server", "mysql-server"]
  

書式設定を使用したクエリ

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value
  

出力は次のようになります。

  http-server
  db-client
  app-server
  mysql-server

wait-for-change 機能を使用してメタデータの変更をクエリする

メタデータ値は VM の実行中に変更される可能性があるため、メタデータ サーバーでは、wait-for-change 機能を使用して、メタデータの変更について通知を受けることができます。このオプションを使用すると、指定したメタデータが変更された場合にのみリクエストが返されます。

この機能は、カスタム メタデータやサーバー定義メタデータでも使用できます。したがって、VM やプロジェクトに変更が加えられた場合でも、カスタム メタデータ エントリが更新された場合でも、プログラムでその変更に対処できます。

たとえば、tags キーに対するリクエストを実行すると、tags メタデータの内容が変更されていた場合にのみ結果が返されます。返される結果には、そのメタデータキーの新しい値が含まれます。

wait-for-change 機能では、リクエストとの照合やタイムアウトの設定もできます。

wait-for-change 機能を使用する場合は、次の点を考慮してください。

• wait-for-change リクエストを実行できるのは、メタデータ エンドポイントに対してか、ディレクトリの内容に対してだけです。ディレクトリ リストに対して wait-for-change リクエストを実行することはできません。これを行うと、リクエストが失敗し、メタデータ サーバーが 400 Invalid Request エラーを返します。

• サービス アカウント トークンに wait-for-change リクエストを実行することはできません。サービス アカウント トークン URL に wait-for-change リクエストを行うと、リクエストは直ちに失敗し、400 Invalid Request エラーが返されます。

wait-for-change リクエストを実行するには、メタデータキーのクエリを実行し、?wait_for_change=true クエリ パラメータを追加します。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。

   curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   指定したメタデータキーが変更されると、クエリで新しい値が返されるようになります。

例

この例では、setInstanceTags method にリクエストが送信されると新しい値が返されるようになります。

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"
  

出力は次のようになります。

  http-server
  db-client
  

wait-for-change リクエストは、ディレクトリの内容に対して再帰的に実行することもできます。

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"
  

変更があった場合は、新しい内容が返されます。

  {"foo":"bar","baz":"bat"}
  

Windows

1. Windows VM に接続します。

2. Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。

   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} `
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true")
   $value
   

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   指定したメタデータキーが変更されると、クエリで新しい値が返されるようになります。

例

指定したメタデータキーが変更されると、クエリで新しい値が返されるようになります。この例では、setInstanceTags method にリクエストが送信されると新しい値が返されるようになります。

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value
  

出力は次のようになります。

  http-server
  db-client
  

wait-for-change リクエストは、ディレクトリの内容に対して再帰的に実行することもできます。

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value
  

変更があった場合は、新しい内容が返されます。

  {"foo":"bar","baz":"bat"}
  

ETag を使用する

wait-for-change クエリを送信すると、そのメタデータの内容が変更されていた場合にレスポンスが返されます。しかし、メタデータの更新と wait-for-change リクエストの送信の間には固有の競合状態があるため、取得するメタデータ値が最新であることを確認できる確実な方法があると便利です。

その方法として使用できるのが last_etag クエリ パラメータです。このクエリ パラメータは、リクエストで指定された ETag 値と、メタデータ サーバーに保存されている ETag 値を比較します。ETag 値が一致した場合は、wait-for-change リクエストが受け入れられます。ETag 値が一致しない場合は、前回 ETag 値を取得してからメタデータの内容が変更されていることになります。この場合は、その最新の値が直ちに返されます。

Linux VM

メタデータキーの最新の ETag 値を取得するには、次の操作を行います。

1. Linux VM に接続します。

2. そのキーに対するリクエストを送信してヘッダーを出力します。これを行うには、-v フラグを指定して curl ツールを使用します。VM インスタンスまたはプロジェクトのメタデータ エントリの現在の ETag を取得するには、次のコマンドを実行します。

   curl -v "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"
   

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   たとえば、次のコマンドを実行すると、tags インスタンスのメタデータキーの現在の ETag 値を取得します。

     user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
     

   出力は次のようになります。

   * About to connect() to metadata port 80 (#0)
   * Trying 169.254.169.254... connected
   * Connected to metadata (169.254.169.254) port 80 (#0)
   > GET /computeMetadata/v1/instance/tags HTTP/1.1
   > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
   > Host: metadata
   > Accept: */*
   >
   < HTTP/1.1 200 OK
   < Content-Type: application/text
   < ETag: 411261ca6c9e654e
   < Date: Wed, 13 Feb 2013 22:43:45 GMT
   < Server: Metadata Server for VM
   < Content-Length: 26
   < X-XSS-Protection: 1; mode=block
   < X-Frame-Options: SAMEORIGIN
   <
   http-server
   db-client

3. その ETag 値を使用するには、wait-for-change リクエストの curl ツールコマンドを使用します。インスタンスまたはプロジェクトのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
     

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • ETAG: メタデータキーの ETag 値。

   この例では、次のコマンドで tags キーに ETag 値を使用し、インスタンスのメタデータ エントリをクエリします。

     user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"
     

   指定した ETag 値がメタデータ サーバーで照合され、値が変更されていた場合は、メタデータキーの新しい内容が返されます。

Windows VM

メタデータキーの最新の ETag 値を取得するには、次の操作を行います。

1. Windows VM に接続します。

2. そのキーに対するリクエストを送信してヘッダーを出力します。Windows では、Invoke-WebRequest コマンドを使用します。VM インスタンスまたはプロジェクトのメタデータ エントリの現在の ETag を取得するには、次のコマンドを実行します。

     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY)
   
   
   $value.Headers.ETag
     

   PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

   • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
   • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
   • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   たとえば、次のコマンドを実行すると、tags インスタンスのメタデータキーの現在の ETag 値を取得します。

     PS C:> 
     $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
     -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
   
   
   $value.Headers.ETag
     

   出力は次のようになります。

     * About to connect() to metadata port 80 (#0)
     * Trying 169.254.169.254... connected
     * Connected to metadata (169.254.169.254) port 80 (#0)
     > GET /computeMetadata/v1/instance/tags HTTP/1.1
     > User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
     > Host: metadata
     > Accept: /
     >
     < HTTP/1.1 200 OK
     < Content-Type: application/text
     < ETag: 411261ca6c9e654e
     < Date: Wed, 13 Feb 2013 22:43:45 GMT
     < Server: Metadata Server for VM
     < Content-Length: 26
     < X-XSS-Protection: 1; mode=block
     < X-Frame-Options: SAMEORIGIN
     <
     http-server
     db-client

3. これで、この ETag 値を wait-for-change リクエストで使用できます。インスタンスまたはプロジェクトのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG")
     $value
     

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • ETAG: メタデータキーの ETag 値。

   この例では、次のコマンドで tags キーに ETag 値を使用し、インスタンスのメタデータ エントリをクエリします。

     PS C:> 
     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
               -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
     $value
     

   指定した ETag 値がメタデータ サーバーで照合され、値が変更されていた場合は、メタデータキーの新しい内容が返されます。

Python

次の Python サンプルは、メタデータ サーバーの変更をプログラムで監視する方法を示しています。

このサンプルでは、最初の ETag が 0 に設定されています。メタデータ サーバーは、ETag 値が 0 のレスポンスを返しません。リクエストで前回の ETag として 0 を指定すると、メタデータ サーバーから最新の値と ETag が返されます。これにより、最初の値と ETag を取得するために必要なコードを省略できます。

last_etag = "0"

while True:
    r = requests.get(
        url,
        params={"last_etag": last_etag, "wait_for_change": True},
        headers=METADATA_HEADERS,
    )

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers["etag"]

タイムアウトを設定する

wait-for-change リクエストで、一定の秒数が経過するとリクエストがタイムアウトになるようにするには timeout_sec パラメータを設定します。timeout_sec パラメータは、リクエストの待機時間を指定の秒数に制限します。その上限に達すると、メタデータキーの現在の内容が返されます。

timeout_sec パラメータを設定した場合、指定の秒数が経過すると、メタデータ値が実際に変更されているかどうかに関係なく、常に結果が返されます。タイムアウトに設定できるのは整数値だけです。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。

     curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
     

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • TIMEOUT: タイムアウト値。

たとえば、次のコマンドは、360 秒後にタイムアウトするように設定された wait-for-change リクエストを実行します。

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"
  

Windows

1. Windows VM に接続します。

2. Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。VM インスタンスまたはプロジェクトのメタデータ エントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。

     $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
             -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT")
     $value
     

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • TIMEOUT: タイムアウト値。

たとえば、次のコマンドは、360 秒後にタイムアウトするように設定された wait-for-change リクエストを実行します。

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value
  

ステータス コード

wait-for-change リクエストを実行すると、リクエストが成功したかどうかを示す標準の HTTP ステータス コードが返されます。結果がエラーになる場合は、ネットワークの状態が原因でリクエストが失敗して、エラーコードが返されている可能性があります。そのような場合は、それらのエラーが認識されて適切に処理されるようにして、アプリケーションをフォールト トレラントにする必要があります。

メタデータ サーバーから返される可能性があるステータスを以下に示します。

ステータス	説明
HTTP 200	正常終了しました。値が変更されたか、指定されている timeout_sec に達したため、リクエストは正常に終了しました。
Error 400	リクエストが無効です。クエリを修正してリクエストを再試行してください。
Error 404	指定したメタデータ値は存在しません。このエラーは、変更の待機中にメタデータが削除された場合にも返されます。
Error 503	一時的なサーバーエラーか一時的なメンテナンス イベントが発生しました。リクエストを再試行してください。

HTTPS メタデータ サーバー エンドポイントを使用してメタデータをクエリする

プレビュー — HTTPS metadata server endpoint

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

HTTPS メタデータ サーバー エンドポイント（https://metadata.google.internal/computeMetadata/v1）は、メタデータ サーバーと VM の間で情報を送信する際のセキュリティを強化します。

HTTPS メタデータ サーバー エンドポイントを使用するには、次の要件を確認してください。

• HTTPS メタデータ サーバー エンドポイント（プレビュー版）へのアクセスをリクエストする必要があります。

  警告: プロジェクトが HTTPS メタデータ サーバー エンドポイントの許可リストに追加されたという確認を受け取るまで、次の作業に進まないでください。

• プロジェクトが許可リストに追加されたら、VM を作成できます。VM は次の要件を満たす必要があります。

  • ゲスト環境が VM 上で実行されている必要があります。
  • VM が Shielded VM である必要があります。これは、HTTPS メタデータ サーバーが証明書の検証に Unified Extensible Firmware Interface（UEFI）と Virtual Trusted Platform Module（vTPM）を必要とするためです。

HTTPS メタデータ サーバー エンドポイントへのクエリの処理方法の概要については、HTTPS メタデータ サーバー エンドポイントをご覧ください。https エンドポイントと http エンドポイントのどちらを使用しても、メタデータ サーバーに同じクエリを実行できます。ただし、https エンドポイントを呼び出すには、クライアント ID 証明書のパスと、場合によってはルート証明書のパスを指定する必要があります。

次のコマンドは、https エンドポイントを使用してメタデータ サーバーにクエリを実行する方法を示しています。

Linux

1. Linux VM に接続します。

2. Linux VM から、curl ツールを使用してクエリを実行し、クライアント ID 証明書を指定します。必要に応じて、ルート証明書を指定します。

   curl "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" \
     -E CLIENT_CERTIFICATE \
     [--cacert ROOT_CERTIFICATE] \
     -H "Metadata-Flavor: Google"
   

   次のように置き換えます。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。
   • CLIENT_CERTIFICATE: クライアント ID 証明書のパス: /run/google-mds-mtls/client.key
   • 省略可: ROOT_CERTIFICATE: ルート証明書 /run/google-mds-mtls/root.crt へのパス。

   たとえば、VM のブートイメージにクエリを実行するには、次のクエリを実行します。

   user@myinst:~$ 
   curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \
     -E /run/google-mds-mtls/client.key \
     -H "Metadata-Flavor: Google"
   

   出力は次のようになります。

   projects/rhel-cloud/global/images/rhel-8-v20210122

   エラー メッセージが表示された場合は、トラブルシューティングのドキュメントをご覧ください。

Windows

1. Windows VM に接続します。

2. 次のいずれかのコマンドを使用して、クライアント ID 証明書を取得します。

   • $cert = Get-PfxCertificate -FilePath "C:\ProgramData\Google\Compute Engine\mds-mtls-client.key.pfx"
     

   • $cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "google.internal" }
     

3. Windows VM から Invoke-RestMethod コマンドを使用し、クライアント ID 証明書を指定してクエリを実行します。

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} -Certificate CLIENT_CERTIFICATE `
             -Uri "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
   $value
   

   次のように置き換えます。

   • CLIENT_CERTIFICATE: VM 上のクライアント ID 証明書のパス。これは、前のステップで設定した $cert 変数です。

   • PATH_TO_METADATA_ENTRY は、値をクエリする VM インスタンスまたはプロジェクトのメタデータキーのパスに置き換えます。キーがインスタンスまたはプロジェクト ディレクトリのサブディレクトリにある場合は、サブディレクトリも含めてください。次に例を示します。

     • プロジェクト メタデータに保存されている project-id メタデータキーを表示するには、project/project-id を指定します。
     • VM インスタンス メタデータに保存されている image メタデータキーを表示するには、instance/image を指定します。
     • プロジェクトまたは VM インスタンス メタデータの attributes サブディレクトリに保存できる enable-oslogin を表示するには、ユースケースに応じて project/attributes/enable-oslogin または instance/attributes/enable-oslogin を指定します。

   たとえば、Windows Server 2019 VM のブートイメージにクエリを実行するには、次のクエリを実行します。

   PS C:\> 
   $value = (Invoke-RestMethod `
             -Headers @{'Metadata-Flavor' = 'Google'} -Certificate $cert `
             -Uri "https://metadata.google.internal/computeMetadata/v1/instance/image")
   $value
   

   出力は次のようになります。

   projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

制限事項

• X-Forwarded-For ヘッダーを含むリクエストは、メタデータ サーバーで自動的に拒否されます。このヘッダーは、一般に、リクエストにプロキシが使用されていることを示します。この場合、承認されたユーザーからのリクエストではない可能性があります。そのようなリクエストは、セキュリティ上の理由からすべて拒否されます。

• curl コマンドを使用してサーバーからメタデータを取得する場合、一部のエンコードされた文字はリクエストパスでサポートされません。エンコードされた文字は、クエリパスでのみサポートされています。

  たとえば、次のリクエストは機能しない場合があります。

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  このリクエストを機能させるには、リクエストパスのサポートされていないエンコードされた文字（%40）を同等の許容値（@）に置き換える必要があります。

  curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/[e-mail]/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

  以下の表に、リクエストパスでサポートされていないエンコード文字をまとめています。

  エンコードされた文字	許容値
  %21	!
  %24	$
  %27	'
  %28	(
  %29	)
  %2A	*
  %2C	,
  %40	@

VM のカスタム メタデータを表示する

Compute Engine VM のカスタム メタデータ値は、次のいずれかの方法で表示できます。

• プロジェクトのメタデータを表示する
• ゾーン メタデータを表示する
• インスタンスのメタデータを表示する

プロジェクトのメタデータを表示する

プロジェクト内のすべての VM に適用されるカスタム メタデータを表示するには、次のいずれかの方法を使用します。

コンソール

1. Google Cloud コンソールで、[メタデータ] ページに移動します。

   [メタデータ] ページに移動

   [メタデータ] ページに、プロジェクトのすべてのカスタム プロジェクト メタデータ エントリが一覧表示されます。

gcloud

プロジェクトのメタデータをクエリするには、gcloud compute project-info describe コマンドを使用します。

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

出力は次のようになります。

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

プロジェクトのメタデータをクエリするには、project.get メソッドに GET リクエストを送信します。

PROJECT_ID は、実際のプロジェクト ID に置き換えます。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID

出力は次のようになります。

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

ゾーン メタデータを表示する

プロジェクトの特定のゾーンにあるすべての VM インスタンスに適用されるカスタム メタデータを表示するには、次のいずれかの方法を使用します。

gcloud

カスタム ゾーン メタデータをクエリするには、gcloud compute project-zonal-metadata describe コマンドを使用します。

gcloud compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

次のように置き換えます。

• PROJECT_ID: プロジェクト ID
• ZONE: ゾーン メタデータを表示するゾーン。

出力は次のようになります。

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

カスタム ゾーン メタデータをクエリするには、instanceSettings().get メソッドに GET リクエストを送信します。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings

次のように置き換えます。

• PROJECT_ID: プロジェクト ID
• ZONE: ゾーン メタデータを表示するゾーン。

出力は次のようになります。

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

インスタンスのメタデータを表示する

プロジェクト内の単一の VM に適用されるメタデータを表示するには、次のいずれかの方法を使用します。

コンソール

1. Google Cloud コンソールで [VM インスタンス] ページに移動します。

   [VM インスタンス] に移動

2. メタデータを表示する VM の名前をクリックします。

   • この VM の SSH 認証鍵。[セキュリティとアクセス] セクションで、[SSH 認証鍵] フィールドを表示します。

     • 値 None は、インスタンスのメタデータに保存された SSH 認証鍵がないことを示します。

     • その他の値は、SSH 認証鍵がインスタンスのメタデータに格納されていることを示します。

   • プロジェクトの SSH 認証鍵。[セキュリティとアクセス] セクションで、[プロジェクト全体の SSH 認証鍵をブロック] フィールドを表示します。

     • 値 On は、インスタンス メタデータのメタデータキー block-project-ssh-keys の値が TRUE であることを示します。

     • 値 Off は、メタデータキー block-project-ssh-keys の値が FALSE であるか、キーが設定されていないことを示します。

   • その他すべてのカスタム メタデータ。[カスタム メタデータ] セクションを表示します。SSH 認証鍵メタデータ以外の、すべてのカスタム メタデータのキーと値が表示されます。

gcloud

gcloud compute instances describe コマンドを使用して、インスタンスのメタデータをクエリします。

gcloud compute instances describe VM_NAME --flatten="metadata[]"

VM_NAME は、メタデータを検索する VM の名前に置き換えます。

出力は次のようになります。

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

特定の VM のメタデータをクエリするには、GET リクエストを instances.get メソッドに送信します。

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

出力は次のようになります。

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

次のように置き換えます。

• PROJECT_ID: プロジェクト ID
• ZONE: VM を配置するゾーン
• VM_NAME: VM の名前

次のステップ

• VM メタデータの詳細を確認する。
• カスタム メタデータの設定方法を学習する。
• ゲスト属性を設定してクエリする方法を学習する。