このページは Cloud Translation API によって翻訳されました。

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

Linux Windows

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

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

準備

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

このページのサンプルをどのように使うかに応じて、タブを選択してください。
コンソール

Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。
gcloud
1. Google Cloud CLI をインストールし、次のコマンドを実行して初期化します。
```
gcloud init
```
  注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。
2. デフォルトのリージョンとゾーンを設定します。
Python

このページの Python サンプルをローカル開発環境から使用するには、gcloud CLI をインストールして初期化し、自身のユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定してください。
1. Google Cloud CLI をインストールします。
2. gcloud CLI を初期化するには:
```
gcloud init
```
3. Google アカウントのローカル認証情報を作成します。
```
gcloud auth application-default login
```
詳細については、ローカル開発環境の認証の設定をご覧ください。
REST

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

必要なロール

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

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

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

VM 内から、Linux では curl ツール、Windows では Invoke-RestMethod などのツールを使用して、デフォルトまたはカスタムメタデータ値をプログラムでクエリできます。

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

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

コンポーネント説明

ルート URL

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

すべてのメタデータ値は、次のルート URL のサブパスとして定義されます。

http://metadata.google.internal/computeMetadata/v1

http://169.254.169.254/computeMetadata/v1

```
http://metadata.goog/computeMetadata/v1
```

リクエストヘッダー

このヘッダーにより、そのリクエストがメタデータ値を取得する目的で送信されたものであり、安全でないソースから意図せず送信されたものではないことが示されるため、リクエストしたデータがメタデータサーバーから返されるようになります。このヘッダーが含まれていないリクエストはメタデータサーバーで拒否されます。

Metadata-Flavor: Google

注: 以前は、リクエストに X-Google-Metadata-Request: True ヘッダーが含まれている必要がありました。どちらのヘッダーもまだサポートされていますが、X-Google-Metadata-Request: True ヘッダーではなく Metadata-Flavor ヘッダーを使用することをおすすめします。

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

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

Linux

Linux VM に接続します。
Linux VM から、curl ツールを使用してクエリを実行します。
- VM インスタンスのメタデータエントリをクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータエントリをクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
```
METADATA_KEY は、値をクエリするインスタンスまたはプロジェクトのメタデータキーに置き換えます。

たとえば、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

Windows VM に接続します。
Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。
- VM インスタンスのメタデータエントリをクエリするには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY")
$value
```
- プロジェクトのメタデータエントリをクエリするには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY")
$value
```
METADATA_KEY は、値をクエリするインスタンスまたはプロジェクトのメタデータキーに置き換えます。

たとえば、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

Linux VM に接続します。
Linux VM から、次のコマンドを実行します。
- VM インスタンスのメタデータディレクトリをクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータディレクトリをクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/" -H "Metadata-Flavor: Google"
```
METADATA_DIRECTORY_NAME は、リスティングをクエリするインスタンスまたはプロジェクトのメタデータディレクトリの名前に置き換えます。

たとえば、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 にアタッチされているディスクのディレクトリです。ディスクエントリをクエリするには、次の手順を完了します。

Windows VM に接続します。
Windows VM から、次のコマンドを実行します。
- VM インスタンスのメタデータディレクトリをクエリするには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/")
$value
```
- プロジェクトのメタデータディレクトリをクエリするには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/")
$value
```
METADATA_DIRECTORY_NAME は、リスティングをクエリするインスタンスまたはプロジェクトのメタデータディレクトリの名前に置き換えます。

たとえば、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

Linux VM に接続します。

Linux VM から、curl ツールを使用してクエリを実行します。

VM インスタンスのメタデータディレクトリリスティングを再帰的にクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
```
プロジェクトのメタデータディレクトリリスティングを再帰的にクエリするには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_DIRECTORY_NAME/?recursive=true" -H "Metadata-Flavor: Google"
```

METADATA_DIRECTORY_NAME は、リスティングを再帰的にクエリするインスタンスまたはプロジェクトのメタデータディレクトリの名前に置き換えます。

たとえば、次のコマンドを実行すると、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

Windows VM に接続します。

Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。

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

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

プロジェクトのメタデータディレクトリリスティングを再帰的にクエリするには、次のコマンドを実行します。

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

METADATA_DIRECTORY_NAME は、リスティングを再帰的にクエリするインスタンスまたはプロジェクトのメタデータディレクトリの名前に置き換えます。

たとえば、次のコマンドを実行すると、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"}]

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

Linux VM に接続します。
Linux VM から、curl ツールを使用してクエリを実行します。
- VM インスタンスのメタデータエントリのクエリレスポンスデータ形式を変更するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータエントリのクエリレスポンスデータ形式を変更するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- 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

Windows VM に接続します。
Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。
- VM インスタンスのメタデータエントリのクエリレスポンスデータ形式を変更するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?alt=DATA_FORMAT")
$value
```
- プロジェクトのメタデータエントリのクエリレスポンスデータ形式を変更するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?alt=DATA_FORMAT")
$value
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- DATA_FORMAT: クエリレスポンスデータ形式（例: text、json）。

例

デフォルトのキーワード

  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

Linux VM に接続します。
Linux VM から、curl ツールを使用してクエリを実行します。
- VM インスタンスのメタデータエントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータエントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
```
METADATA_KEY は、値をクエリするインスタンスまたはプロジェクトのメタデータキーに置き換えます。

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

例

この例では、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

Windows VM に接続します。
Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。
```
  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/METADATA_KEY?wait_for_change=true")
  $value
  
```
- VM インスタンスのメタデータエントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true")
$value
```
- プロジェクトのメタデータエントリに wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true")
$value
```
METADATA_KEY は、wait-for-change リクエストを実行するインスタンスまたはプロジェクトのメタデータキーに置き換えます。

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

例

指定したメタデータキーが変更されると、クエリで新しい値が返されるようになります。この例では、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 値を取得するには、次の操作を行います。

Linux VM に接続します。

そのキーに対するリクエストを送信してヘッダーを出力します。これを行うには、-v フラグを指定して curl ツールを使用します。

VM インスタンスのメタデータエントリの現在の ETag を取得するには、次のコマンドを実行します。
```
curl -v "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY" -H "Metadata-Flavor: Google"
```
プロジェクトのメタデータエントリの現在の ETag を取得するには、次のコマンドを実行します。
```
curl -v "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY" -H "Metadata-Flavor: Google"
```

METADATA_KEY は、値をクエリするインスタンスまたはプロジェクトのメタデータキーに置き換えます。

たとえば、次のコマンドを実行すると、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

その ETag 値を使用するには、wait-for-change リクエストの curl ツールコマンドを使用します。
- インスタンスのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- 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 値を取得するには、次の操作を行います。

Windows VM に接続します。

そのキーに対するリクエストを送信してヘッダーを出力します。Windows では、Invoke-WebRequest コマンドを使用します。

VM インスタンスのメタデータエントリの現在の ETag を取得するには、次のコマンドを実行します。

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

$value.Headers.ETag

プロジェクトのメタデータエントリの現在の ETag を取得するには、次のコマンドを実行します。

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

$value.Headers.ETag

METADATA_KEY は、値をクエリするインスタンスまたはプロジェクトのメタデータキーに置き換えます。

たとえば、次のコマンドを実行すると、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

これで、この ETag 値を wait-for-change リクエストで使用できます。
- インスタンスのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
$value
```
- プロジェクトのメタデータの wait-for-change リクエストに ETag 値を使用するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&last_etag=ETAG")
$value
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- 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

Linux VM に接続します。
Linux VM から、curl ツールを使用してクエリを実行します。
- VM インスタンスのメタデータエントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
```
- プロジェクトのメタデータエントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
curl "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- 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

Windows VM に接続します。
Windows VM から、Invoke-RestMethod コマンドを使用してクエリを実行します。
- VM インスタンスのメタデータエントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
$value
```
- プロジェクトのメタデータエントリにタイムアウト値を指定して wait-for-change リクエストを実行するには、次のコマンドを実行します。
```
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/project/METADATA_KEY?wait_for_change=true&timeout_sec=TIMEOUT")
$value
```
次のように置き換えます。
- METADATA_KEY: 値をクエリするインスタンスまたはプロジェクトのメタデータキー。
- 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`	一時的なサーバーエラーか一時的なメンテナンスイベントが発生しました。リクエストを再試行してください。

制限事項

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/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"
```
以下の表に、リクエストパスでサポートされていないエンコード文字をまとめています。
エンコードされた文字許容値
%21
!
%24
$
%27
'
%28
(
%29
)
%2A
*
%2C
,
%40
@

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

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

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

プロジェクト全体のメタデータを表示する
プロジェクトのゾーンメタデータを表示する（プレビュー）
インスタンスのメタデータを表示する

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

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

コンソール

Google Cloud コンソールで、[メタデータ] ページに移動します。
[メタデータ] に移動
- [メタデータ] タブでは、SSH 認証鍵メタデータを除くほとんどのカスタムプロジェクトメタデータを確認できます。
- [SSH 認証鍵] タブでは、プロジェクトレベルの SSH 認証鍵メタデータをすべて確認できます。

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 beta compute project-zonal-metadata describe コマンドを使用します。

gcloud beta 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/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings

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

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

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

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

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

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

コンソール

Google Cloud コンソールで [VM インスタンス] ページに移動します。
[VM インスタンス] に移動
メタデータを表示する 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 メタデータの詳細を確認する。
カスタムメタデータの設定方法を学習する。
ゲスト属性を設定してクエリする方法を学習する。

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

準備

コンソール

gcloud

Python

REST

必要なロール

必要な権限

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

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

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

Linux

Windows

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

Linux

Windows

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

Linux

Windows

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

Linux

例

Windows

例

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

Linux

Windows

ETag を使用する

Linux VM

Windows VM

Python

タイムアウトを設定する

Linux

Windows

ステータス コード

制限事項

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

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

コンソール

gcloud

REST

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

gcloud

REST

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

コンソール

gcloud

REST

次のステップ

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

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

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

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

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

ステータスコード

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

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