Ressourceneinstellungen verwalten

In diesem Leitfaden wird beschrieben, wie Sie Ressourceneinstellungen verwalten. Mit den Ressourceneinstellungen können Sie die Einstellungen für Ihre Google Cloud-Projekte, -Ordner und -Organisation zentral konfigurieren. Mit jeder Ressourceneinstellung können Sie einen Aspekt eines unterstützten Dienstes steuern.

Hinweise

Weitere Informationen zu Ressourceneinstellungen und ihrer Funktionsweise finden Sie in der Übersicht zu Ressourceneinstellungen.

API aktivieren

Die Resource Settings API kann für einzelne Projekte aktiviert werden.

Google Cloud Console

So aktivieren Sie die Resource Settings API:

Zu APIs und Dienste

Wählen Sie das Projekt aus, mit dem Sie auf die API zugreifen.
Klicken Sie auf die Schaltfläche APIs und Dienste aktivieren.
Suchen Sie nach "Resource Settings".
Klicken Sie in den Suchergebnissen auf "Resource Settings API".
Wenn "API aktiviert" angezeigt wird, ist die API bereits aktiviert. Falls nicht, klicken Sie auf die Schaltfläche Aktivieren.

gcloud

Verwenden Sie den Befehl gcloud services enable, um die Resource Settings API zu aktivieren:

gcloud services enable resourcesettings.googleapis.com

Erforderliche Berechtigungen

Welche Berechtigungen Sie benötigen, hängt von der auszuführenden Aktion ab.

Um diese Berechtigungen zu erhalten, bitten Sie Ihren Administrator, die vorgeschlagene Rolle auf der entsprechenden Ebene der Ressourcenhierarchie zu gewähren.

Ressourceneinstellungen aufrufen

Zum Anzeigen der für eine Ressource verfügbaren Ressourceneinstellungen sowie der lokalen und effektiven Einstellungswerte für eine Ressource benötigen Sie die Rolle Betrachter von Ressourceneinstellungen (roles/resourcesettings.viewer) oder eine andere Rolle mit den folgenden Berechtigungen:

resourcesettings.settings.get
resourcesettings.settings.list

Ressourceneinstellungen verwalten

Zum Erstellen, Aktualisieren und Löschen von Werten für Ressourceneinstellungen benötigen Sie die Rolle Administrator für Ressourceneinstellungen (roles/resourcesettings.admin) oder eine andere Rolle mit den folgenden Berechtigungen:

resourcesettings.settings.get
resourcesettings.settings.list
resourcesettings.settings.update

Verfügbare Einstellungen auflisten

Sie können eine Liste aller verfügbaren Ressourceneinstellungen für eine bestimmte Ressource abrufen. Diese Liste enthält alle Ressourceneinstellungen, die auf die Ressource angewendet werden können. Ressourceneinstellungen im Vorschaustatus sind nur für Nutzer verfügbar, denen die explizite Berechtigung zur Verwendung erteilt wurde.

gcloud

Mit dem folgenden gcloud resource-settings list-Befehl rufen Sie eine Liste aller Einstellungen ab, die für eine Ressource verfügbar sind:

gcloud resource-settings list --RESOURCE_ID

Dabei ist RESOURCE_ID die ID des Ordners, des Projekts oder der Organisation, für die Sie die verfügbaren Ressourceneinstellungen finden möchten. Beispiel: --project=7890123456

API

Wenn Sie eine Liste aller für eine Ressource verfügbaren Einstellungen abrufen möchten, verwenden Sie eine der folgenden settings.list-Methoden. Verwenden Sie die Methode, die dem Ressourcentyp entspricht, für den Sie die Einstellungen auflisten möchten:

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings

Ersetzen Sie Folgendes:

ACCESS_TOKEN: Ihr OAuth 2.0-Zugriffstoken.
RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die Sie die verfügbaren Ressourceneinstellungen finden möchten. Beispiel: projects/7890123456

Beispielantwort

Die Antwort auf eine Auflistungsanfrage für folders/4567890123 sieht in etwa so aus:

{
  "settings" : [
    {
      "name": "folders/4567890123/settings/net-preferredDnsServers",
      "metadata":  {
        "displayName": "Preferred DNS Servers",
        "description": "The DNS servers to be used by VMs associated with this resource.",
        "read_only": false,
        "data_type" : "STRING_SET",
        "default_value" : {
          "string_set_value" : {
            "values" : [ "8.8.8.8" ],
          }
        }
      }
    },
    {
      "name": "folders/4567890123/settings/text-defaultTextColor",
      "metadata":  {
        "displayName": "Default Text Color",
        "description": "The default text color for this resource.",
        "read_only": false,
        "data_type" : "STRING",
        "default_value" : {
          "string_value" : "black"
        }
      }
    },
    ...
  ]
}

Das Feld name ist der Kurzname der Ressourceneinstellung, der in API- und gcloud CLI-Anfragen für diese Einstellung verwendet werden soll.

Lokalen Einstellungswert ändern

Sie können den lokalen Einstellungswert einer bestimmten Ressourceneinstellung ändern. Wenn Sie einen lokalen Einstellungswert festlegen, werden alle übernommenen Werte für den effektiven Einstellungswert überschrieben. Wenn Sie den lokalen Einstellungswert aufheben, wird jeder lokale Einstellungswert, der auf eine Herkunftsressource angewendet wird, übernommen, wodurch er zum effektiven Wert wird.

gcloud

Verwenden Sie den folgenden gcloud resource-settings set-value-Befehl, um den lokalen Einstellungswert für eine Ressourceneinstellung für eine Ressource zu ändern:

gcloud resource-settings set-value --value-file=FILE_PATH

Ersetzen Sie FILE_PATH durch den Pfad zu einer YAML- oder JSON-Datei, die die Ressourceneinstellung enthält.

JSON-Beispieldatei:

{
  "localValue" : {
    "stringSetValue": {
      "values": [
        "8.8.8.8",
        "8.8.4.4",
      ]
    }
  },
  "name": "RESOURCE_ID/settings/SETTING_NAME"
}

Ersetzen Sie Folgendes:

RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die Sie die lokale Ressourceneinstellung aktualisieren möchten. Beispiel: projects/7890123456
SETTING_NAME: Der Kurzname der Ressourceneinstellung, die Sie aktualisieren möchten.

Verwenden Sie den Befehl gcloud resource-settings unset-value, um den lokalen Einstellungswert für eine Ressource aufzuheben:

gcloud resource-settings unset-value SETTING_NAME \
  --RESOURCE_ID

Ersetzen Sie Folgendes:

SETTING_NAME: Der Kurzname der Ressourceneinstellung, für die Sie den lokalen Wert aufheben möchten.
RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die Sie die verfügbaren Ressourceneinstellungen finden möchten. Beispiel: projects/7890123456

API

Verwenden Sie die Methode settings.patch, um den lokalen Einstellungswert für eine Ressourceneinstellung für eine Ressource zu ändern. Verwenden Sie die Methode, die dem Ressourcentyp entspricht, für den Sie die Einstellungen aktualisieren möchten:

curl -X PATCH -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -d \
  '{
    "localValue": {
      "stringSetValue": {
        "values": [ "8.8.8.8", "8.8.4.4" ]
      }
    }
  }
  ' https://resourcesettings.googleapis.com/v1/RESOURCE_ID/settings/net-preferredDnsServers

Ersetzen Sie Folgendes:

ACCESS_TOKEN: Ihr OAuth 2.0-Zugriffstoken.
RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die Sie die verfügbaren Ressourceneinstellungen finden möchten. Beispiel: projects/7890123456

Wenn Sie diese Anfrage ohne lokalen Wert in der JSON-Datei stellen, deaktivieren Sie den lokalen Einstellungswert und die Ressource übernimmt die Einstellung des übergeordneten Werts oder verwendet die von Google verwaltete Standardeinstellung.

Nachdem Sie eine erfolgreiche Anfrage gesendet haben, erhalten Sie eine Antwort, die den lokalen Wert enthält, der für diese Einstellung erstellt wurde, und ein etag-Feld, das Sie bei nachfolgenden Aktualisierungsanfragen einschließen müssen.

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "localValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w==",
}

Einstellung für lokalen oder effektiven Wert anzeigen

Sie können den lokalen oder effektiven Wert einer Ressourceneinstellung für eine bestimmte Ressource aufrufen.

gcloud

Verwenden Sie den Befehl gcloud resource-settings describe, um den lokalen Wert einer Ressourceneinstellung für eine bestimmte Ressource anzuzeigen:

gcloud resource-settings describe SETTING_NAME \
  --RESOURCE_ID

Ersetzen Sie Folgendes:

SETTING_NAME: Der Kurzname der Ressourceneinstellung, für die Sie den lokalen oder effektiven Wert ermitteln möchten.
RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die verfügbare Ressourceneinstellungen gefunden werden sollen. Beispiel: --project=7890123456

Wenn Sie das Flag --effective hinzufügen, erhalten Sie den effektiven Wert, der stattdessen für diese Ressource ausgewertet wird.

API

Mit der Methode settings.get können Sie den lokalen oder effektiven Wert einer Ressourceneinstellung für eine bestimmte Ressource aufrufen. Verwenden Sie die Methode, die dem Ressourcentyp entspricht, für den Sie die Einstellungen auflisten möchten:

curl -X GET -H "Content-Type: application/json" -H \
  "Authorization: Bearer $ACCESS_TOKEN" \
  https://resourcesettings.googleapis.com/v1/RESOURCE_ID \
  /settings/SETTING_NAME?view=VIEW_PARAMETER

Ersetzen Sie Folgendes:

ACCESS_TOKEN: Ihr OAuth 2.0-Zugriffstoken.
RESOURCE_ID: Die ID des Ordners, des Projekts oder der Organisation, für die Sie die verfügbaren Ressourceneinstellungen finden möchten. Beispiel: projects/7890123456
SETTING_NAME: Der Kurzname der Ressourceneinstellung, für die Sie Rückgabewerte wünschen.
VIEW_PARAMETER: SETTING_VIEW_LOCAL_VALUE, um den lokalen Einstellungswert zurückzugeben, oder SETTING_VIEW_EFFECTIVE_VALUE, um den effektiven Wert bei dieser Ressource zurückzugeben.

Beispielantwort

Die Antwort auf eine GET-Anfrage für folders/4567890123 sieht in etwa so aus:

{
  "name": "folders/4567890123/settings/net-preferredDnsServers",
  "value": {
    "stringSetValue": {
      "values": [ "8.8.8.8", "8.8.4.4" ]
    }
  }
  "etag": "O2VWGxZU01VnAfRU4Mu97w=="
}

Übernahme

Die Ressourceneinstellung, die für eine bestimmte Ressource wirksam wird, wird durch Übernahme ausgewertet. Sie können den übernommenen Wert einer Ressource überschreiben, indem Sie einen lokalen Wert festlegen. Dies wirkt sich auch auf die Einstellungswerte aus, die von den untergeordneten Elementen dieser Ressource übernommen werden. Weitere Informationen zur Übernahme von Ressourceneinstellungen finden Sie unter Effektive Einstellungswerte.

Effektive Werte abrufen

Sie können den effektiven Wert einer Einstellung für eine bestimmte Ressource mithilfe der API oder der gcloud CLI abrufen. Eine ausführliche Anleitung finden Sie unter Einstellung für lokalen oder effektiven Wert ansehen. Im folgenden Beispiel sind die Werte für die Ressourceneinstellung „Bevorzugte DNS-Server“ für eine Organisation, einen Ordner innerhalb dieser Organisation und ein Unterordner innerhalb dieses Ordners festgelegt:

Die effektiven Werte für jede dieser Ressourcen werden so ausgewertet:

organizations/111 hat keinen lokalen Wert und hat keine übergeordnete Ressource, von der übernommen werden kann. Daher würde die von Google verwaltete Standardeinstellung 8.8.8.8 verwendet werden.
- Wenn Sie die Methode describe verwenden, um den effektiven Wert für eine Ressource abzurufen, und dafür die von Google verwaltete Standardeinstellung verwendet wird, sind diese Informationen in der Antwort enthalten. Beispiel:
```
{
  "name": "organizations/111/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.8.8" ] # Google-managed default
    }
  }
}
```
folders/222 hat die lokale Werteinstellung 8.8.4.4 und übernimmt daher nicht von der übergeordneten Ressource.
- Wenn Sie den Wert einer Ressource mit der Methode describe abrufen und es sich um einen lokal festgelegten Wert handelt, werden diese Informationen in die Antwort aufgenommen. Beispiel:
```
{
  "name": "folders/222/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # set on folders/222
    }
  }
}
```
folders/333 hat keinen lokalen Wert, die übergeordnete Ressource aber schon. Es übernimmt den lokalen Einstellungswert folders/222 und wird daher als 8.8.4.4 ausgewertet.
- Wenn Sie die Methode describe verwenden, um den effektiven Wert für eine Ressource abzurufen, und sie diesen Wert von einer übergeordneten Ressource übernimmt, sind diese Informationen in der Antwort enthalten. Beispiel:
```
{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}
```

Übernommenen Wert überschreiben

Wenn Sie den lokalen Einstellungswert folders/333 für die Einstellung "Bevorzugte DNS-Server" ändern, ändert sich der effektive Wert. Verwenden Sie beispielsweise die Methode patch, um den lokalen Einstellungswert folders/333 auf 192.168.1.1 zu aktualisieren. Eine ausführliche Anleitung finden Sie unter Lokalen Einstellungswert ändern.

Wenn Sie die Methode describe für die aktualisierte folders/333-Ressource verwenden, sehen Sie, dass der effektive Wert jetzt 192.168.1.1 ist:

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "192.168.1.1" ] # set on folders/333
    }
  }
}

Auf Übernahmewert zurücksetzen

Wenn eine Ressource den lokalen Wert einer übergeordneten Ressource übernimmt, verwenden Sie die API-Methode patch ohne in der Abfrage festgelegten lokalen Wert oder den Befehl unset-value der gcloud CLI. Eine ausführliche Anleitung finden Sie unter Lokalen Einstellungswert ändern.

Wenn Sie beispielsweise den lokalen Wert für folders/333 aufheben, wird wieder der effektive Wert von der nächsten übergeordneten Ressource, folders/222, übernommen. Wenn Sie die Methode describe für die aktualisierte Ressource folders/333 verwenden, sehen Sie, dass der effektive Wert jetzt 8.8.4.4 ist:

{
  "name": "folders/333/settings/net-preferredDnsServers",
  "effectiveValue": {
    "stringSetValue": {
      "values": [ "8.8.4.4" ] # inherited from folders/222
    }
  }
}