VM-Metadaten aufrufen und abfragen

Jede virtuelle Maschine (VM) speichert ihre Metadaten in Verzeichnissen auf einem Metadatenserver. Ihre VM hat automatisch ohne zusätzliche Autorisierung Zugriff auf diese Metadatenserver-API. Sie können die in den folgenden Abschnitten dieses Dokuments erläuterten Methoden verwenden, um VM-Metadatenwerte aufzurufen und abzufragen:

Wenn beim Zugriff auf den Metadatenserver Fehler auftreten, lesen Sie den Hilfeartikel Fehlerbehebung bei Zugriffsproblemen mit Metadatenserver.

Hinweise

  • Verwenden Sie für Windows Server-VMs PowerShell 3.0 oder höher. Wir empfehlen, die kopierten Codeblöcke mit ctrl+v einzufügen.
  • Sehen Sie sich die Grundlagen dazu an, wie Sie VM-Metadaten für Compute Engine definieren, kategorisieren und anordnen können. Weitere Informationen finden Sie unter Informationen zu VM-Metadaten.
  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud-Dienste und APIs überprüft. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei Compute Engine authentifizieren.

    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
    2. Set a default region and zone.

      3. Python

      Wenn Sie die Python Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, installieren und initialisieren Sie die gcloud CLI und richten dann die Standardanmeldedaten für Anwendungen mit Ihren Nutzeranmeldedaten ein.

      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.

      Weitere Informationen unter Set up authentication for a local development environment.

      REST

      Verwenden Sie die von der gcloud CLI bereitgestellten Anmeldedaten, um die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung zu verwenden.

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

        gcloud init

      Weitere Informationen finden Sie unter Für die Verwendung von REST authentifizieren in der Dokumentation zur Google Cloud-Authentifizierung.

Erforderliche Rollen

Die folgenden Rollen und Berechtigungen sind erforderlich, um benutzerdefinierte Metadaten über die Google Cloud Console, die Google Cloud CLI oder REST außerhalb der VM aufzurufen. Wenn Sie die Metadaten programmatisch innerhalb der VM abfragen, benötigen Sie nur die Rollen und Berechtigungen für die Verbindung zur VM.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen benutzerdefinierter Metadaten von außerhalb der VM benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Aufrufen benutzerdefinierter Metadaten von außerhalb der VM erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um benutzerdefinierte Metadaten von außerhalb der VM aufzurufen:

  • Um benutzerdefinierte Projektmetadaten aufzurufen: compute.projects.get für das Projekt
  • Um benutzerdefinierte zonale Metadaten aufzurufen: compute.instanceSettings.get für die Instanzeinstellungen in der erforderlichen Zone im Projekt
  • Um benutzerdefinierte Metadaten für eine VM-Instanz aufzurufen: compute.instances.get auf der VM
  • Wenn Ihre VMs Dienstkonten verwenden: iam.serviceAccounts.actAs für die Dienstkonten oder das Projekt

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Metadaten programmatisch abfragen

Sie können auf alle Metadaten zugreifen, indem Sie die Metadatenwerteinträge programmatisch innerhalb einer Linux- oder Windows-VM abfragen. Innerhalb Ihrer VM können Sie Ihre Metadatenwerte auf eine der folgenden Arten programmatisch abfragen, indem Sie Tools wie curl unter Linux oder Invoke-RestMethod unter Windows verwenden:

Metadatenserver-Endpunkte

Für die programmatische Abfrage von Metadaten innerhalb einer VM stehen die folgenden Metadatenserver-Endpunkte zur Verfügung:

  • Sie können den Metadatenserver für alle VMs über den HTTP-Endpunkt (http://metadata.google.internal/computeMetadata/v1) abfragen.

  • Bei geschützten VMs können Sie den Metadatenserver mit einer der folgenden Methoden abfragen:

In den meisten Beispielen in diesem Dokument wird der HTTP-Endpunkt verwendet. Sie können jedoch unabhängig davon, ob Sie den https- oder den http-Endpunkt verwenden, auf dieselben Metadateneinträge zugreifen.

Bestandteile einer Metadatenanfrage

In der folgenden Tabelle sind die wichtigsten Teile einer Metadatenabfrage zusammengefasst.

Komponenten Beschreibung
Stamm-URLs

Alle Metadatenwerte werden als Subpfade unterhalb der folgenden Stamm-URLs definiert:

  • HTTP-Endpunkt: 
    • http://metadata.google.internal/computeMetadata/v1
    • http://169.254.169.254/computeMetadata/v1
    • http://metadata.goog/computeMetadata/v1
  • https-Endpunkt (Vorabversion): 
    • https://metadata.google.internal/computeMetadata/v1
      Dies ist die einzige URL, die während der Vorschauphase unterstützt wird.
Anfrage-Header

Dieser Header weist darauf hin, dass eine Anfrage zum Aufruf von Metadatenwerten gesendet wurde und diese nicht unbeabsichtigt aus einer unsicheren Quelle kommen. Auf diese Weise kann der Metadatenserver Ihnen die entsprechenden Daten zurückgeben. Ohne diesen Header lehnt der Metadatenserver Ihre Anfrage ab.

Metadata-Flavor: Google

Einzelnen Metadateneintrag abfragen

Verwenden Sie die folgenden Befehle, um einen einzelnen Metadateneintrag abzufragen.

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um einen Metadateneintrag für eine VM-Instanz oder ein Projekt abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Führen Sie beispielsweise die folgende Abfrage aus, um das Boot-Image für die VM abzufragen:

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

    Die Ausgabe sieht etwa so aus:

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

Windows

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um einen Metadateneintrag für eine VM-Instanz oder ein Projekt abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Führen Sie beispielsweise die folgende Abfrage aus, um das Boot-Image für die VM abzufragen:

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

    Die Ausgabe sieht etwa so aus:

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

Metadatenverzeichniseinträge abfragen

Verwenden Sie die folgenden Befehle, um Metadaten-Verzeichniseinträge abzufragen. Verzeichniseinträge sind Metadateneinträge, die andere Metadatenschlüssel enthalten. Alle Metadateneinträge, die mit einem Schrägstrich enden, sind Verzeichniseinträge.

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Führen Sie den folgenden Befehl aus, um das Metadatenverzeichnis einer VM-Instanz oder eines Projekts über Ihre Linux-VM abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_DIRECTORY durch den Pfad zum Metadatenverzeichnis der VM-Instanz oder des Projekts, für das Sie die Einträge rekursiv abfragen möchten. Beispiel:

    • Wenn Sie den Verzeichniseintrag für die Projektmetadaten von attributes aufrufen möchten, müssen Sie den Pfad project/attributes/ angeben.
    • Wenn Sie den Metadatenverzeichniseintrag der VM-Instanz disks aufrufen möchten, müssen Sie den Pfad instance/disks/ angeben.

    Betrachten Sie beispielsweise den Eintrag disks/, bei dem es sich um ein Verzeichnis von Laufwerken handelt, die mit der VM verbunden sind. Führen Sie die folgenden Schritte aus, um den Eintrag disks/ abzufragen:

    1. Führen Sie den curl-Toolbefehl im Laufwerksverzeichnis aus.

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

      Die Ausgabe sieht in etwa so aus:

      0/
1/
2/

    2. Wenn Sie weitere Informationen zum Verzeichnis 0/ des Laufwerks benötigen, können Sie die spezifische URL für dieses Verzeichnis abfragen:

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

      Die Ausgabe sieht etwa so aus:

      device-name
index
mode
type

    3. Führen Sie Folgendes aus, um dann den Laufwerktyp (type) für die Laufwerke 0/ abzufragen:

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

      Die Ausgabe sieht etwa so aus:

      PERSISTENT

Windows

Der Eintrag disks/ ist ein Verzeichnis von Laufwerken, das an die VM angehängt ist. Führen Sie die folgenden Schritte aus, um den Laufwerkeintrag abzufragen:

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Führen Sie den folgenden Befehl aus, um das Metadatenverzeichnis einer VM-Instanz oder eines Projekts über Ihre Windows-VM abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_DIRECTORY durch den Pfad zum Metadatenverzeichnis der VM-Instanz oder des Projekts, für das Sie die Einträge rekursiv abfragen möchten. Beispiel:

    • Wenn Sie den Verzeichniseintrag für die Projektmetadaten von attributes aufrufen möchten, müssen Sie den Pfad project/attributes/ angeben.
    • Wenn Sie den Metadatenverzeichniseintrag der VM-Instanz disks aufrufen möchten, müssen Sie den Pfad instance/disks/ angeben.

    Betrachten Sie beispielsweise den Eintrag disks/, bei dem es sich um ein Verzeichnis von Laufwerken handelt, die mit der VM verbunden sind. Führen Sie die folgenden Schritte aus, um den Eintrag disks/ abzufragen:

    1. Führen Sie den Invoke-RestMethod-Befehl im Laufwerksverzeichnis aus.

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

      Die Ausgabe sieht etwa so aus:

      0/
1/
2/

    2. Wenn Sie weitere Informationen zum Verzeichnis 0/ des Laufwerks benötigen, können Sie die spezifische URL für dieses Verzeichnis abfragen:

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

      Die Ausgabe sieht etwa so aus:

      device-name
index
mode
type

    3. Führen Sie Folgendes aus, um dann den Laufwerktyp (type) für die Laufwerke 0/ abzufragen:

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

      Die Ausgabe sieht etwa so aus:

      PERSISTENT

Verzeichniseinträge rekursiv abfragen

Wenn Sie alle Inhalte in einem Verzeichnis zurückgeben möchten, verwenden Sie den Abfrageparameter recursive=true mit Ihrer Anfrage:

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um die Einträge für das Metadatenverzeichnis einer VM-Instanz oder eines Projekts rekursiv abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_DIRECTORY durch den Pfad zum Metadatenverzeichnis der VM-Instanz oder des Projekts, für das Sie die Einträge rekursiv abfragen möchten. Beispiel:

    • Wenn Sie den Verzeichniseintrag für die Projektmetadaten von attributes aufrufen möchten, müssen Sie den Pfad project/attributes/ angeben.
    • Wenn Sie den Metadatenverzeichniseintrag der VM-Instanz disks aufrufen möchten, müssen Sie den Pfad instance/disks/ angeben.

    Mit dem folgenden Befehl werden beispielsweise die Instanzmetadateneinträge für das Verzeichnis disks/ rekursiv abgefragt.

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

    Die Ausgabe sieht in etwa so aus:

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

    Standardmäßig werden rekursive Inhalte im JSON-Format angezeigt. Wenn Sie diese Inhalte im Textformat zurückgeben möchten, hängen Sie den Abfrageparameter alt=text an:

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

    Die Ausgabe sieht etwa so aus:

      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. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um die Einträge für das Metadatenverzeichnis einer VM-Instanz oder eines Projekts rekursiv abzufragen:

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

    Ersetzen Sie PATH_TO_METADATA_DIRECTORY durch den Pfad zum Metadatenverzeichnis der VM-Instanz oder des Projekts, für das Sie die Einträge rekursiv abfragen möchten. Beispiel:

    • Wenn Sie den Verzeichniseintrag für die Projektmetadaten von attributes aufrufen möchten, müssen Sie den Pfad project/attributes/ angeben.
    • Wenn Sie den Metadatenverzeichniseintrag der VM-Instanz disks aufrufen möchten, müssen Sie den Pfad instance/disks/ angeben.

    Mit dem folgenden Befehl werden beispielsweise die Instanzmetadateneinträge für das Verzeichnis disks/ rekursiv abgefragt.

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

    Die Ausgabe sieht in etwa so aus:

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

    Standardmäßig werden rekursive Inhalte im JSON-Format angezeigt. Wenn Sie diese Inhalte im Textformat zurückgeben möchten, hängen Sie den Abfrageparameter alt=text an:

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

    Die Ausgabe sieht etwa so aus:

    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

Ausgabe der Abfrage formatieren

Standardmäßig besitzt jeder Endpunkt ein vordefiniertes Format für die Antwort. Einige Endpunkte können JSON-Daten zurückgeben, während andere die Daten als String darstellen. Sie können das Standardformat für Daten mit den Abfrageparametern alt=json oder alt=text ändern, die Daten als JSON-String oder als Klartextdarstellung zurückgeben.

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um das Datenformat der Abfrageantwort für den Metadateneintrag einer VM-Instanz oder eines Projekts zu ändern:

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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • DATA_FORMAT: das Format, in dem die Abfrageantwortdaten abgerufen werden sollen, z. B. text oder json.

Beispiel

Der Schlüssel tags gibt beispielsweise Daten automatisch im JSON-Format zurück. Sie können stattdessen Daten im Textformat zurückgeben, indem Sie den Abfrageparameter alt=text angeben.

Standardsuchanfrage

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

Die Ausgabe sieht etwa so aus:

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

Abfrage mit Formatierung

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

Die Ausgabe sieht etwa so aus:

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

Windows

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um das Datenformat der Abfrageantwort für den Metadateneintrag einer VM-Instanz oder eines Projekts zu ändern:

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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • DATA_FORMAT: das Format, in dem die Abfrageantwortdaten abgerufen werden sollen, z. B. text oder json.

Beispiel

Der Schlüssel tags gibt beispielsweise Daten automatisch im JSON-Format zurück. Sie können stattdessen Daten im Textformat zurückgeben, indem Sie den Abfrageparameter alt=text angeben.

Standardsuchanfrage

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

Die Ausgabe sieht etwa so aus:

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

Abfrage mit Formatierung

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

Die Ausgabe sieht etwa so aus:

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

Metadatenänderungen mit dem wait-for-change-Feature abfragen

Da sich Metadatenwerte ändern können, während Ihre VM ausgeführt wird, kann der Metadatenserver mithilfe des Features wait-for-change über Metadatenänderungen informiert werden. Bei dieser Option gibt die Anfrage nur dann eine Ausgabe zurück, wenn sich die angegebenen Metadaten geändert haben.

Sie können dieses Feature für benutzerdefinierte oder serverdefinierte Metadaten verwenden. Sobald sich also etwas an Ihrer VM oder Ihrem Projekt ändert, oder jemand einen benutzerdefinierten Metadateneintrag aktualisiert, können Sie programmatisch auf die Änderung reagieren.

Sie können beispielsweise eine Anfrage für den Schlüssel tags ausführen, sodass die Anfrage nur zurückgegeben wird, wenn sich der Inhalt der Metadaten der Tags geändert hat. Wird die Anfrage zurückgegeben, beinhaltet sie den neuen Wert des Metadatenschlüssels.

Mit dem Feature wait-for-change können Sie auch einen Abgleich mit Ihrer Anfrage durchführen und Zeitlimits festlegen.

Beachten Sie bei der Arbeit mit dem Feature wait-for-change Folgendes:

  • Sie können eine wait-for-change-Anfrage nur für einen Metadatenendpunkt oder rekursiv für den Inhalt eines Verzeichnisses ausführen. Sie können keine wait-for-change-Anfrage für einen Verzeichniseintrag ausführen. Wenn Sie dies versuchen, kann der Metadatenserver Ihre Anfrage nicht ausführen und gibt den Fehler 400 (ungültige Anfrage) zurück.

  • Sie können keine wait-for-change-Anfrage für ein Dienstkonto-Token ausführen. Wenn Sie versuchen, eine wait-for-change-Anfrage an die URL des Dienstkonto-Tokens zu senden, schlägt die Anfrage sofort fehl und gibt den Fehler 400 (ungültige Anfrage) zurück.

Zum Ausführen einer wait-for-change-Anfrage fragen Sie einen Metadatenschlüssel ab und hängen den Abfrageparameter ?wait_for_change=true an:

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um eine wait-for-change-Anfrage für den Metadateneintrag einer VM-Instanz oder eines Projekts durchzuführen:

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

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Wenn der angegebene Metadatenschlüssel verändert wurde, gibt die Anfrage den neuen Wert zurück.

Beispiele

In diesem Beispiel wurde eine Anfrage an setInstanceTags method gerichtet und gibt neue Werte zurück:

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

Die Ausgabe sieht in etwa so aus:

  http-server
  db-client

Sie können auch eine wait-for-change-Anfrage rekursiv für den Inhalt eines Verzeichnisses durchführen:

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

Der Metadatenserver gibt die neuen Inhalte an, sollte es Veränderungen gegeben haben:

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

Windows

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um eine wait-for-change-Anfrage für den Metadateneintrag einer VM-Instanz oder eines Projekts durchzuführen:

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

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Wenn der angegebene Metadatenschlüssel verändert wurde, gibt die Anfrage den neuen Wert zurück.

Beispiele

Wenn der angegebene Metadatenschlüssel verändert wurde, gibt die Anfrage den neuen Wert zurück. In diesem Beispiel wurde eine Anfrage an setInstanceTags method gerichtet und gibt neue Werte zurück:

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

Die Ausgabe sieht in etwa so aus:

  http-server
  db-client

Sie können auch eine wait-for-change-Anfrage rekursiv für die Inhalte eines Verzeichnisses durchführen:

  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

Der Metadatenserver gibt die neuen Inhalte an, sollte es Veränderungen gegeben haben:

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

ETags verwenden

Wenn Sie eine wait-for-change-Abfrage senden, gibt der Metadatenserver eine Antwort zurück, wenn sich im Inhalt dieser Metadaten etwas geändert hat. Jedoch gibt es immer einen Wettlauf zwischen der Aktualisierung von Metadaten und einer wait-for-change-Anfrage. Deswegen lohnt es sich, eine verlässliche Methode zu haben, um herauszufinden, ob Sie den neuesten Metadatenwert erhalten.

Dafür haben wir Ihnen den last_etag-Anfrageparameter zur Verfügung gestellt, der Ihren ETag-Wert mit dem vergleicht, der auf dem Metadatenserver gespeichert ist. Wenn die ETag-Werte übereinstimmen, wird die Anfrage wait-for-change akzeptiert. Stimmen die ETag-Werte nicht überein, dann bedeutet das, dass sich seit dem letzten Aufruf des ETag-Werts etwas verändert hat. Der Metadatenserver sendet diesen neuen Wert sofort zurück.

Linux-VMs

Führen Sie die folgenden Schritte aus, um den aktuellen ETag-Wert für einen Metadatenschlüssel abzurufen:

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Stellen Sie eine Anfrage an diesen Schlüssel und drucken Sie die Header. Verwenden Sie dazu das curl-Tool mit dem Flag -v. Führen Sie den folgenden Befehl aus, um das aktuelle ETag für den Metadateneintrag einer VM-Instanz oder eines Projekts abzurufen:

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

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Mit dem folgenden Befehl wird beispielsweise der aktuelle ETag-Wert für den Metadatenschlüssel tags der Instanz abgerufen.

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

    Die Ausgabe sieht in etwa so aus:

    * 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. Sie können diesen ETag-Wert dann zusammen mit dem curl-Toolbefehl in der wait-for-change-Anfrage verwenden. Führen Sie den folgenden Befehl aus, um den ETag-Wert für die wait-for-change-Anfrage von Instanz- oder Projektmetadaten zu verwenden:

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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • ETAG: der ETag-Wert für den Metadatenschlüssel.

    In diesem Beispiel verwendet der folgende Befehl den ETag-Wert für den Schlüssel tags und fragt den Metadateneintrag der Instanz ab.

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

    Der Metadatenserver überprüft diesen ETag-Wert und gibt die neuen Inhalte Ihres Metadatenschlüssels zurück, sollte er sich ändern.

Windows-VMs

Führen Sie die folgenden Schritte aus, um den aktuellen ETag-Wert für einen Metadatenschlüssel abzurufen:

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Stellen Sie eine Anfrage an diesen Schlüssel und drucken Sie die Header. Verwenden Sie unter Windows den Invoke-WebRequest-Befehl. Führen Sie den folgenden Befehl aus, um das aktuelle ETag für den Metadateneintrag einer VM-Instanz oder eines Projekts abzurufen:

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


    $value.Headers.ETag

    Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

    • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
    • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
    • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Mit dem folgenden Befehl wird beispielsweise der aktuelle ETag-Wert für den Metadatenschlüssel tags der Instanz abgerufen.

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


    $value.Headers.ETag

    Die Ausgabe sieht in etwa so aus:

      * 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. Sie können den ETag-Wert dann in Ihrer wait-for-change-Anfrage verwenden. Führen Sie den folgenden Befehl aus, um den ETag-Wert für die wait-for-change-Anfrage von Instanz- oder Projektmetadaten zu verwenden:

      $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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • ETAG: der ETag-Wert für den Metadatenschlüssel.

    In diesem Beispiel verwendet der folgende Befehl den ETag-Wert für den Schlüssel tags und fragt den Metadateneintrag der Instanz ab.

      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

    Der Metadatenserver überprüft diesen ETag-Wert und gibt die neuen Inhalte Ihres Metadatenschlüssels zurück, sollte er sich ändern.

Python

Das folgende Beispiel für Python zeigt, wie Sie den Metadatenserver programmatisch auf Änderungen überwachen können.

In diesem Beispiel wird das Anfangs-ETag auf 0 gesetzt. Der Metadatenserver gibt keine Antwort mit 0 als ETag-Wert zurück. Wenn 0 in einer Anfrage als letztes ETag erscheint, antwortet der Metadatenserver mit dem aktuellen Wert und dem ETag. Dadurch wird ein Teil des Codes gespart, der zum Abrufen des Anfangswerts und des ETags erforderlich ist.

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

Zeitlimits festlegen

Wenn Sie möchten, dass Ihre wait-for-change-Anfrage nach einer bestimmten Anzahl von Sekunden abläuft, können Sie den Parameter timeout_sec festlegen. Der Parameter timeout_sec beschränkt die Wartezeit Ihrer Anfrage auf die von Ihnen angegebene Anzahl an Sekunden. Erreicht die Anfrage diesen Wert, ruft sie den aktuellen Inhalt des Metadatenschlüssels auf.

Wenn Sie den timeout_sec-Parameter einrichten, wird die Anfrage jeweils unabhängig davon, ob sich die Metadatenwerte verändert haben, nach Ablauf der Zeit zurückgegeben. Nur ganze Zahlen dürfen als Zeitlimit festgelegt werden.

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um eine wait-for-change-Anfrage mit einem Zeitüberschreitungswert für den Metadateneintrag einer VM-Instanz oder eines Projekts durchzuführen:

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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • TIMEOUT: der Zeitüberschreitungswert.

Mit dem folgenden Befehl wird beispielsweise eine wait-for-change-Anfrage ausgeführt, die nach 360 Sekunden mit einer Zeitüberschreitung abläuft:

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

Windows

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod, um eine Abfrage zu stellen. Führen Sie den folgenden Befehl aus, um eine wait-for-change-Anfrage mit einem Zeitüberschreitungswert für den Metadateneintrag einer VM-Instanz oder eines Projekts durchzuführen:

      $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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • TIMEOUT: der Zeitüberschreitungswert.

Mit dem folgenden Befehl wird beispielsweise eine wait-for-change-Anfrage ausgeführt, die nach 360 Sekunden mit einer Zeitüberschreitung abläuft:

  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

Statuscodes

Wenn Sie eine wait-for-change-Anfrage ausführen, gibt der Metadatenserver Standard-HTTP-Statuscodes zurück, um Erfolg oder Misserfolg anzuzeigen. Tritt ein Fehler auf, kann es sein, dass der Metadatenserver Ihre Anfrage abweist und Ihnen einen Fehlercode schickt. Geschieht dies, sollten Sie Ihre Anwendung so ändern, dass sie fehlertolerant ist und diese Art von Fehlern erkennen und mit ihnen umgehen kann.

Mögliche Statusanzeigen des Metadatenservers:

Status Beschreibung
HTTP 200 Fertig! Ein Wert wurde geändert oder der für timeout_sec angegebene Wert wurde erreicht und die Anfrage wurde erfolgreich beantwortet.
Error 400 Ihre Anfrage war ungültig. Bitte korrigieren Sie Ihre Anfrage und versuchen Sie es noch einmal.
Error 404 Der Metadatenwert, den Sie angegeben haben, existiert nicht mehr. Der Metadatenserver zeigt diesen Fehler an, wenn Ihre Metadaten gelöscht wurden, während Sie auf eine Veränderung warten.
Error 503 Ein temporärer Serverfehler oder ein temporäres Wartungsereignis ist aufgetreten. Wiederholen Sie die Anfrage.

Metadaten mit dem HTTPS-Metadatenserver-Endpunkt abfragen

Der HTTPS-Metadatenserver-Endpunkt (https://metadata.google.internal/computeMetadata/v1) bietet zusätzliche Sicherheit für die Übertragung von Informationen zwischen dem Metadatenserver und der VM.

Für die Verwendung des HTTPS-Metadatenserver-Endpunkts gelten die folgenden Anforderungen:

  • Sie müssen Zugriff auf die Vorabversion des HTTPS-Metadatenserver-Endpunkts anfordern.

  • Nachdem Ihr Projekt der Zulassungsliste hinzugefügt wurde, können Sie die VM erstellen. Die VM muss die folgenden Anforderungen erfüllen:

    • Die Gastumgebung muss auf der VM ausgeführt werden.
    • Die VM muss eine Shielded VM sein. Das liegt daran, dass der HTTPS-Metadatenserver für die Überprüfung von Zertifikaten die Verwendung von UEFI (Unified Extensible Firmware Interface) und vTPM (Virtual Trusted Platform Module) erfordert.

Eine Übersicht dazu, wie Abfragen an den HTTPS-Metadatenserver-Endpunkt verarbeitet werden, finden Sie unter HTTPS-Metadatenserver-Endpunkt. Sie können dieselben Abfragen an den Metadatenserver senden, unabhängig davon, ob Sie den https- oder den http-Endpunkt verwenden. Wenn Sie den https-Endpunkt aufrufen möchten, müssen Sie jedoch den Pfad zu den Client-Identitätszertifikaten und in einigen Fällen auch das Stammzertifikat angeben.

Die folgenden Befehle zeigen, wie Sie den Metadatenserver über den HTTPS-Endpunkt abfragen.

Linux

  1. Stellen Sie eine Verbindung zu Ihrer Linux-VM her.

  2. Verwenden Sie in Ihrer Linux-VM das curl-Tool, um eine Abfrage zu stellen und das Zertifikat für die Clientidentität anzugeben. Optional können Sie auch das Stammzertifikat angeben.

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

    Ersetzen Sie Folgendes:

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.
    • CLIENT_CERTIFICATE: der Pfad zum Zertifikat für die Clientidentität: /run/google-mds-mtls/client.key.
    • Optional: ROOT_CERTIFICATE: der Pfad zum Stammzertifikat: /run/google-mds-mtls/root.crt.

    Führen Sie beispielsweise die folgende Abfrage aus, um das Boot-Image für eine VM abzufragen:

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

    Die Ausgabe sieht in etwa so aus:

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

    Wenn eine Fehlermeldung angezeigt wird, lesen Sie die Dokumentation zur Fehlerbehebung.

Windows

  1. Stellen Sie eine Verbindung zu Ihrer Windows-VM her.

  2. Rufen Sie das Zertifikat für die Clientidentität mit einem der folgenden Befehle ab:

    • $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. Verwenden Sie in Ihrer Windows-VM den Befehl Invoke-RestMethod und geben Sie das Client-Identitätszertifikat an, um eine Abfrage zu stellen.

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

    Ersetzen Sie Folgendes:

    • CLIENT_CERTIFICATE: der Pfad zum Zertifikat für die Clientidentität auf der VM. Das ist die Variable $cert, die im vorherigen Schritt festgelegt wurde.

    • Ersetzen Sie PATH_TO_METADATA_ENTRY durch den Pfad zur VM-Instanz oder zum Projektmetadatenschlüssel, für den Sie den Wert abfragen möchten. Wenn sich der Schlüssel in einem Unterverzeichnis des Instanz- oder Projektverzeichnisses befindet, muss auch das Unterverzeichnis angegeben werden. Beispiel:

      • Geben Sie project/project-id an, um den Metadatenschlüssel project-id aufzurufen, der in den Projektmetadaten gespeichert ist.
      • Geben Sie instance/image an, um den Metadatenschlüssel image aufzurufen, der in den Metadaten der VM-Instanz gespeichert ist.
      • Wenn Sie die enable-oslogin aufrufen möchten, die im Unterverzeichnis „attributes“ der Projekt- oder VM-Instanzmetadaten gespeichert werden kann, geben Sie je nach Anwendungsfall project/attributes/enable-oslogin oder instance/attributes/enable-oslogin an.

    Wenn Sie beispielsweise das Boot-Image für eine Windows Server 2019-VM abfragen möchten, führen Sie die folgende Abfrage aus:

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

    Die Ausgabe sieht in etwa so aus:

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

Beschränkungen

  • Anfragen mit dem Header X-Forwarded-For werden automatisch vom Metadatenserver abgewiesen. Dieser Header zeigt normalerweise an, dass die Anfrage weitergeleitet wurde und eventuell nicht von einem autorisierten Nutzer stammt. Aus Sicherheitsgründen werden Anfragen dieser Art abgelehnt.

  • Wenn Sie den Befehl curl verwenden, um Metadaten vom Server abzurufen, beachten Sie, dass einige codierte Zeichen im Anfragepfad nicht unterstützt werden. Codierte Zeichen werden nur im Abfragepfad unterstützt.

    Die folgende Anforderung funktioniert beispielsweise eventuell nicht:

    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"

    Damit diese Anfrage funktioniert, ersetzen Sie das nicht unterstützte codierte Zeichen im Anfragepfad (%40) durch den entsprechenden zulässigen Wert (@).

    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"

    In der folgenden Tabelle sind die codierten Zeichen aufgeführt, die in Anfragepfaden nicht unterstützt werden.

    Codiertes Zeichen Zulässiger Wert
    %21 
    !
    %24 
    $
    %27 
    '
    %28 
    (
    %29 
    )
    %2A 
    *
    %2C 
    ,
    %40 
    @

Benutzerdefinierte Metadaten für Ihre VMs aufrufen

Sie können die benutzerdefinierten Metadatenwerte für Ihre Compute Engine-VMs auf eine der folgenden Arten aufrufen:

Projektmetadaten anzeigen

Verwenden Sie eine der folgenden Methoden, um benutzerdefinierte Metadaten aufzurufen, die für alle VMs in Ihrem Projekt gelten.

Console

  1. Rufen Sie in der Google Cloud Console die Seite Metadaten auf.

    Zur Seite "Metadaten"

    Auf der Seite Metadaten sehen Sie eine Liste aller benutzerdefinierten Projektmetadateneinträge für Ihr Projekt.

gcloud

Verwenden Sie den Befehl gcloud compute project-info describe, um Projektmetadaten abzufragen:

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

Die Ausgabe sieht in etwa so aus:

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

REST

Erstellen Sie zum Abfragen von Projektmetadaten eine GET-Anfrage an die project.get-Methode.

Ersetzen Sie dabei PROJECT_ID durch Ihre Projekt-ID.

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

Die Ausgabe sieht in etwa so aus:

"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"
    }
  ]
}, ...

Zonale Metadaten aufrufen

Verwenden Sie eine der folgenden Methoden, um benutzerdefinierte Metadaten aufzurufen, die für alle VM-Instanzen in einer bestimmten Zone in einem Projekt gelten.

gcloud

Verwenden Sie den Befehl gcloud compute project-zonal-metadata describe, um die benutzerdefinierten zonalen Metadaten abzufragen.

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID.
  • ZONE: die Zone, für die Sie die zonalen Projektmetadaten aufrufen möchten.

Die Ausgabe sieht in etwa so aus:

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

REST

Senden Sie eine GET-Anfrage an die Methode instanceSettings().get, um die benutzerdefinierten zonalen Metadaten abzufragen.

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID.
  • ZONE: die Zone, für die Sie die zonalen Projektmetadaten aufrufen möchten.

Die Ausgabe sieht in etwa so aus:

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

Instanzmetadaten aufrufen

Verwenden Sie eine der folgenden Methoden, um Metadaten aufzurufen, die für eine einzelne VM in Ihrem Projekt gelten.

Console

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zu „VM-Instanzen“

  2. Klicken Sie auf den Namen der VM, für die Sie Metadaten aufrufen möchten.

    • SSH-Schlüssel für diese VM. Sehen Sie sich im Abschnitt Sicherheit und Zugriff das Feld SSH-Schlüssel an.

      • Der Wert von None gibt an, dass keine SSH-Schlüssel in Instanzmetadaten gespeichert sind.

      • Jeder andere Wert gibt an, dass SSH-Schlüssel in Instanzmetadaten gespeichert sind.

    • SSH-Schlüssel für ein Projekt. Sehen Sie sich im Abschnitt Sicherheit und Zugriff das Feld Projektweite SSH-Schlüssel blockieren an.

      • Der Wert On gibt an, dass der Wert des Metadatenschlüssels block-project-ssh-keys in den Instanzmetadaten TRUE ist.

      • Der Wert von Off gibt an, dass der Metadatenschlüssel block-project-ssh-keys den Wert FALSE hat oder der Schlüssel nicht festgelegt ist.

    • Alle anderen benutzerdefinierten Metadaten. Rufen Sie den Abschnitt Benutzerdefinierte Metadaten auf. Sie sehen alle benutzerdefinierten Metadatenschlüssel und -werte außer SSH-Schlüsselmetadaten.

gcloud

Verwenden Sie den Befehl gcloud compute instances describe, um Instanzmetadaten abzufragen:

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

Ersetzen Sie VM_NAME durch den Namen der VM, für die Sie Metadaten suchen möchten.

Die Ausgabe sieht in etwa so aus:

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

REST

Um Metadaten für eine bestimmte VM abzufragen, senden Sie eine GET-Anfrage an die instances.get-Methode.

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

Die Ausgabe sieht in etwa so aus:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID
  • ZONE: die Zone, in der sich die VM befindet
  • VM_NAME: der Name der VM

Nächste Schritte