Rollen für Dienst-Agents erstellen und zuweisen

In Google Cloud werden Dienst-Agents auf Projekt-, Ordner- und Organisationsebene automatisch erstellt, wenn Sie Google Cloud-Dienste aktivieren und verwenden. Manchmal werden diesen Dienst-Agents auch automatisch Rollen zugewiesen, mit denen sie in Ihrem Namen Ressourcen erstellen und darauf zugreifen können.

Bei Bedarf können Sie auch Google Cloud bitten, Dienst-Agents auf Projekt-, Ordner- und Organisationsebene für einen Dienst zu erstellen, bevor Sie den Dienst verwenden. Wenn Sie Google Cloud bitten, Dienst-Agents zu erstellen, können Sie Dienst-Agents Rollen zuweisen, bevor Sie einen Dienst verwenden. Wenn noch kein Dienst-Agent erstellt wurde, können Sie dem Dienst-Agent keine Rollen zuweisen.

Diese Option ist nützlich, wenn Sie eine der folgenden Strategien zum Verwalten Ihrer Zulassungsrichtlinien verwenden:

Ein deklaratives Framework wie Terraform. Wenn Ihre Terraform-Konfiguration nicht die Rollen der Dienst-Agents enthält, werden diese Rollen beim Anwenden der Konfiguration widerrufen. Wenn Sie Dienst-Agents erstellen und ihnen in Ihrer Terraform-Konfiguration Rollen zuweisen, sorgen Sie dafür, dass diese Rollen nicht widerrufen werden.
Ein Richtliniensystem als Code, das Kopien Ihrer aktuellen Zulassungsrichtlinien in einem Code-Repository speichert. Wenn Sie Google Cloud Dienst-Agents automatisch Rollen zuweisen lassen, werden diese Rollen in der tatsächlichen Zulassungsrichtlinie angezeigt, jedoch nicht in der gespeicherten Kopie der Zulassungsrichtlinie. Um diese Inkonsistenz zu beheben, können Sie diese Rollen falsch widerrufen. Wenn Sie Dienst-Agents erstellen und ihnen Rollen proaktiv zuweisen, können Sie Abweichungen zwischen Ihrem Code-Repository und Ihren tatsächlichen Zulassungsrichtlinien verhindern.

Nachdem Sie die Erstellung des Dienst-Agents ausgelöst haben, müssen Sie den Dienst-Agents die Rollen zuweisen, die ihnen normalerweise automatisch zugewiesen werden. Wenn Sie das nicht tun, funktionieren einige Dienste möglicherweise nicht richtig. Dies liegt daran, dass Dienst-Agents, die auf Anfrage eines Nutzers erstellt werden, nicht automatisch Rollen zugewiesen werden.

Hinweise

Enable the Resource Manager API.
Enable the API
Informationen zu Dienst-Agents

Erforderliche Rollen

Zum Erstellen des Dienst-Agents müssen Sie keine IAM-Berechtigungen haben. Für andere Aufgaben auf dieser Seite benötigen Sie jedoch bestimmte IAM-Berechtigungen:

Um die Berechtigung zu erhalten, die Sie für die Auflistung von verfügbaren Diensten und ihren Endpunkten brauchen, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Service Usage-Betrachter (roles/serviceusage.serviceUsageViewer) für das Projekt, den Ordner oder die Organisation zu gewähren, für die Sie die verfügbaren Dienste auflisten möchten. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigung serviceusage.services.list, die zum Auflisten der verfügbaren Dienste und ihrer Endpunkte erforderlich ist.
Sie können diese Berechtigung auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Um Berechtigungen zu erhalten, die Sie brauchen, um den Dienst-Agents Zugriff zu gewähren, bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt, den Ordner oder die Organisation zuzuweisen, für den Sie den Zugriff gewähren wollen:
- Gewähren Sie Dienst-Agents Zugriff auf ein Projekt: Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin)
- Gewähren Sie Dienst-Agents Zugriff auf einen Ordner: Ordneradministrator (roles/resourcemanager.folderAdmin)
- Gewähren Sie Dienst-Agents Zugriff auf Projekte, Ordner und Organisationen: Organisationsadministrator (roles/resourcemanager.organizationAdmin)
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Gewähren des Zugriffs für die Dienst-Agents erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um den Dienst-Agents Zugriff zu gewähren:
- Gewähren Sie Dienst-Agents Zugriff auf ein Projekt:
  - resourcemanager.projects.getIamPolicy
  - resourcemanager.projects.setIamPolicy
- Gewähren Sie Dienst-Agents Zugriff auf einen Ordner:
  - resourcemanager.folders.getIamPolicy
  - resourcemanager.folders.setIamPolicy
- Gewähren Sie Dienst-Agents Zugriff auf eine Organisation:
  - resourcemanager.organizations.getIamPolicy
  - resourcemanager.organizations.setIamPolicy
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Zu erstellende Dienst-Agents identifizieren

So ermitteln Sie die Dienst-Agents auf Projekt-, Ordner- und Organisationsebene, die Sie von Google Cloud zum Erstellen bitten müssen:

Erstellen Sie eine Liste der von Ihnen verwendeten Dienste und ihrer API-Endpunkte. Verwenden Sie eine der folgenden Methoden, um alle verfügbaren Dienste und ihre Endpunkte aufzurufen:
Console

Rufen Sie in der Google Cloud Console die Seite API-Bibliothek auf.

Zur API-Bibliothek

Der API-Endpunkt ist der Dienstname, der im Abschnitt Zusätzliche Details aufgeführt ist.
gcloud

Mit dem Befehl gcloud services list werden alle verfügbaren Dienste für ein Projekt aufgelistet.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
- EXPRESSION: Optional. Ein Ausdruck zum Filtern der Ergebnisse. Der folgende Ausdruck filtert beispielsweise nach allen Diensten, deren Namen googleapis.com, aber nicht sandbox enthalten:
  name ~ googleapis.com AND name !~ sandbox
  Eine Liste der Filterausdrücke finden Sie unter gcloud topic filters.
- LIMIT: Optional. Die maximale Anzahl von aufzulistenden Ergebnissen. Der Standardwert ist unlimited.
Führen Sie folgenden Befehl aus:
Linux, macOS oder Cloud Shell
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (PowerShell)
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (cmd.exe)

Hinweis: Wenn dieser Befehl ' als Anführungszeichen verwendet, ersetzen Sie diese einfachen Anführungszeichen durch doppelte Anführungszeichen. Wenn Anführungszeichen verschachtelt sind, verwenden Sie \", um die inneren Anführungszeichen zu maskieren.
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Die Antwort enthält die Namen und Titel aller verfügbaren Dienste. Der API-Endpunkt ist der Wert im Feld NAME.
REST

Die Methode services.list der Service Usage API listet alle verfügbaren Dienste für ein Projekt auf.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- RESOURCE_TYPE: Der Ressourcentyp, für den Sie die verfügbaren Dienste auflisten möchten. Verwenden Sie projects, folders, oder organizations.
- RESOURCE_ID: Die ID des Google Cloud-Projekts, -Ordners oder der -Organisation, für die Sie die verfügbaren Dienste auflisten möchten. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
- PAGE_SIZE: Optional. Die Anzahl der Dienste, die in der Antwort enthalten sein sollen. Der Standardwert ist 50 und der Höchstwert 200. Wenn die Anzahl der Dienste die Seitengröße überschreitet, enthält die Antwort ein Seitenumbruchtoken, mit dem Sie die nächste Ergebnisseite abrufen können.
- NEXT_PAGE_TOKEN: Optional. Das Seitenumbruchtoken, das in einer früheren Antwort von dieser Methode zurückgegeben wurde. Wenn dieser Wert angegeben wird, beginnt die Liste der Dienste dort, wo die vorherige Anfrage endet.
HTTP-Methode und URL:
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
Die Antwort enthält die Namen und Titel aller verfügbaren Dienste für die Ressource. Wenn die Anzahl der verfügbaren Dienste die Seitengröße überschreitet, enthält die Antwort auch ein Paginierungstoken.

Der API-Endpunkt ist der Wert im Feld name.
Suchen Sie auf der Referenz zum Dienst-Agent nach jedem API-Endpunkt.

Wenn der Endpunkt in der Tabelle aufgeführt ist, suchen Sie alle Dienst-Agents für diesen Endpunkt. Ignorieren Sie alle Dienst-Agents, deren E-Mail-Adresse den Platzhalter IDENTIFIER enthält. Diese Dienst-Agents gelten für dienstspezifische Ressourcen, nicht für Projekte, Ordner oder Organisationen.

Notieren Sie für jeden Dienst-Agent auf Projekt-, Ordner- und Organisationsebene Folgendes:
- Das Format der E-Mail-Adresse des Dienst-Agents.
- Die Rolle, die dem Dienst-Agent gegebenenfalls zugewiesen wurde.

Erstellen eines Trigger-Dienst-Agents

Nachdem Sie wissen, welche Dienst-Agents Sie erstellen müssen, können Sie Google Cloud bitten, sie zu erstellen.

Wenn Sie Google Cloud bitten, Dienst-Agents zu erstellen, stellen Sie ihm einen Dienst und eine Ressource zur Verfügung. Anschließend erstellt Google Cloud alle Dienst-Agents für diesen Dienst und diese Ressource.

gcloud

Gehen Sie für jeden Dienst, für den Sie Dienst-Agents erstellen müssen, so vor:

Prüfen Sie die E-Mail-Adressen des Dienst-Agents für den Dienst. Verwenden Sie die Platzhalter in den E-Mail-Adressen, um zu ermitteln, für welche Ressourcen Sie Dienst-Agents erstellen müssen:

Platzhalter	Dienst-Agents erstellen
`PROJECT_NUMBER`	Jedes Projekt, in dem Sie den Dienst verwenden
`FOLDER_NUMBER`	Jeder Ordner, in dem Sie den Dienst verwenden
`ORGANIZATION_NUMBER`	Jede Organisation, in der Sie den Dienst verwenden

Erstellen Sie Dienst-Agents für jede Ressource.

Mit dem Befehl gcloud beta services identity create werden alle Dienst-Agents für die angegebene API und Ressource erstellt.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:
- ENDPOINT: Der Endpunkt der API, für die Sie einen Dienst-Agent erstellen möchten, z. B. aiplatform.googleapis.com.
- RESOURCE_TYPE: Der Ressourcentyp, für den Sie einen Dienst-Agent erstellen möchten. Verwenden Sie project, folder oder organization.
- RESOURCE_ID: Die ID des Google Cloud-Projekts, -Ordners oder der -Organisation, für die Sie einen Dienst-Agent erstellen möchten. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
  
  Sie können für jeweils eine Ressource Dienst-Agents erstellen. Wenn Sie Dienst-Agents für mehrere Ressourcen erstellen müssen, führen Sie den Befehl für jede Ressource einmal aus.
Führen Sie folgenden Befehl aus:
Linux, macOS oder Cloud Shell
```
gcloud beta services identity create --service=ENDPOINT \
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (PowerShell)
```
gcloud beta services identity create --service=ENDPOINT `
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (cmd.exe)
```
gcloud beta services identity create --service=ENDPOINT ^
    --RESOURCE_TYPE=RESOURCE_ID
```
Die Antwort enthält die E-Mail-Adresse des primären Dienst-Agents des Dienstes. Diese E-Mail-Adresse enthält die numerische ID des Projekts, des Ordners oder der Organisation, für die Sie Dienst-Agents erstellt haben.

Wenn der Dienst keinen primären Dienst-Agent hat, enthält die Antwort keine E-Mail-Adresse.

Das folgende Beispiel zeigt eine Antwort für einen Dienst mit einem primären Dienst-Agent.
```
Service identity created: service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com
```
Optional: Notieren Sie sich die E-Mail-Adresse des Dienst-Agents in der Antwort, falls vorhanden. Diese E-Mail-Adresse identifiziert den primären Dienst-Agent des Dienstes. Mit dieser ID können Sie dem primären Dienst-Agent Rollen zuweisen.

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Anbieterreferenzdokumentation zu Terraform.

Gehen Sie für jeden Dienst, für den Sie Dienst-Agents erstellen müssen, so vor:

Prüfen Sie die E-Mail-Adressen des Dienst-Agents für den Dienst. Verwenden Sie die Platzhalter in den E-Mail-Adressen, um zu ermitteln, für welche Ressourcen Sie Dienst-Agents erstellen müssen:

Platzhalter	Dienst-Agents erstellen
`PROJECT_NUMBER`	Jedes Projekt, in dem Sie den Dienst verwenden
`FOLDER_NUMBER`	Jeder Ordner, in dem Sie den Dienst verwenden
`ORGANIZATION_NUMBER`	Jede Organisation, in der Sie den Dienst verwenden

Erstellen Sie Dienst-Agents für jede Ressource. Mit dem folgenden Code werden beispielsweise alle Dienst-Agents auf Projektebene für AI Platform erstellt:

Hinweis: Terraform unterstützt nur das Erstellen von Dienst-Agents auf Projektebene. Verwenden Sie die Google Cloud CLI oder REST API, um das Erstellen von Dienst-Agents auf Ordner- und Organisationsebene auszulösen.

data "google_project" "default" {
}

# Create all project-level aiplatform.googleapis.com service agents
resource "google_project_service_identity" "default" {
  provider = google-beta

  project = data.google_project.default.project_id
  service = "aiplatform.googleapis.com"
}

REST

Gehen Sie für jeden Dienst, für den Sie Dienst-Agents erstellen müssen, so vor:

Prüfen Sie die E-Mail-Adressen des Dienst-Agents für den Dienst. Verwenden Sie die Platzhalter in den E-Mail-Adressen, um zu ermitteln, für welche Ressourcen Sie Dienst-Agents erstellen müssen:

Platzhalter	Dienst-Agents erstellen
`PROJECT_NUMBER`	Jedes Projekt, in dem Sie den Dienst verwenden
`FOLDER_NUMBER`	Jeder Ordner, in dem Sie den Dienst verwenden
`ORGANIZATION_NUMBER`	Jede Organisation, in der Sie den Dienst verwenden

Erstellen Sie Dienst-Agents für jede Ressource.

Die Methode services.generateServiceIdentity der Service Usage API erstellt alle Dienst-Agents für die angegebene API und Ressource.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- RESOURCE_TYPE: Der Ressourcentyp, für den Sie einen Dienst-Agent erstellen möchten. Verwenden Sie projects, folders, oder organizations.
- RESOURCE_ID: Die ID des Google Cloud-Projekts, -Ordners oder der -Organisation, für die Sie Dienst-Agents erstellen möchten. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
  
  Sie können für jeweils eine Ressource Dienst-Agents erstellen. Wenn Sie Dienst-Agents für mehrere Ressourcen erstellen müssen, senden Sie für jede Ressource eine Anfrage.
- ENDPOINT: Der Endpunkt der API, für die Sie einen Dienst-Agent erstellen möchten, z. B. aiplatform.googleapis.com.
HTTP-Methode und URL:
```
POST https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity
```
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity"
```
PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity" | Select-Object -Expand Content
```
Die Antwort enthält ein Operation, das den Status Ihrer Anfrage angibt. Mit der Methode operations.get können Sie den Status des Vorgangs prüfen:

Abgeschlossene Vorgänge enthalten die E-Mail-Adresse des primären Dienst-Agents des Dienstes. Diese E-Mail-Adresse enthält die numerische ID des Projekts, des Ordners oder der Organisation, für die Sie Dienst-Agents erstellt haben.

Wenn der Dienst keinen primären Dienst-Agent hat, enthält die Antwort keine E-Mail-Adresse.

Das folgende Beispiel zeigt einen abgeschlossenen Vorgang für einen Dienst mit einem primären Dienst-Agent.
```
{
  "name": "operations/finished.DONE_OPERATION",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.serviceusage.v1beta1.ServiceIdentity",
    "email": "service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com",
    "uniqueId": "112245693826560101651"
  }
}
```
Optional: Notieren Sie sich die E-Mail-Adresse des Dienst-Agents in der Antwort, falls vorhanden. Diese E-Mail-Adresse identifiziert den primären Dienst-Agent des Dienstes. Mit dieser ID können Sie dem primären Dienst-Agent Rollen zuweisen.

Dienst-Agents Rollen zuweisen

Nachdem Google Cloud die erforderlichen Dienst-Agents für Ihre Projekte, Ordner und Organisationen erstellt hat, verwenden Sie die E-Mail-Adressen der Dienst-Agents, um ihnen Rollen zuzuweisen.

Wenn Sie Google Cloud aufgefordert haben, Dienst-Agents zu erstellen, müssen Sie diesen Dienst-Agents die Rollen zuweisen, die sie normalerweise automatisch erhalten. Wenn Sie das nicht tun, funktionieren einige Dienste möglicherweise nicht richtig. Dies liegt daran, dass Dienst-Agents, die auf Anfrage eines Nutzers erstellt werden, nicht automatisch Rollen zugewiesen werden.

Informationen zum Identifizieren automatisch gewährter Rollen finden Sie unter Zu erstellende Dienst-Agents identifizieren.

E-Mail-Adresse des Dienst-Agents suchen

So finden Sie die E-Mail-Adresse eines Dienst-Agents:

gcloud

Suchen Sie das E-Mail-Adressformat des Dienst-Agents, falls Sie dies noch nicht getan haben. Dieses Format ist in der Referenz zum Dienst-Agent dokumentiert.
Ersetzen Sie alle Platzhalter in der E-Mail-Adresse durch das entsprechende Projekt, den Ordner oder die Organisationsnummer.

Wenn der Dienst-Agent ein primärer Dienst-Agent ist, können Sie seine E-Mail-Adresse abrufen, indem Sie für den Dienst die Erstellung des Dienst-Agents auslösen. Der Befehl zum Auslösen der Dienst-Agent-Erstellung gibt die E-Mail-Adresse des primären Dienst-Agents zurück.

Terraform

Suchen Sie das E-Mail-Adressformat des Dienst-Agents, falls Sie dies noch nicht getan haben. Dieses Format ist in der Referenz zum Dienst-Agent dokumentiert.
Ersetzen Sie alle Platzhalter in der E-Mail-Adresse durch Ausdrücke, die auf das entsprechende Projekt, den Ordner oder die Organisationsnummer verweisen.

Betrachten Sie beispielsweise die folgende Situation:
- Das Format der E-Mail-Adresse lautet service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com.
- Der Dienst-Agent ist für ein Projekt mit dem Label default bestimmt.
In diesem Fall lautet die E-Mail-Adresse des Dienst-Agents so:
```
service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
```

Wenn ein Dienst-Agent der primäre Dienst-Agent für einen Dienst ist, können Sie seine E-Mail-Adresse alternativ aus dem Attribut email der Ressource google_project_service_identity abrufen.

Wenn Sie beispielsweise einen google_project_service_identity-Block mit der Bezeichnung default haben, können Sie die E-Mail-Adresse des primären Dienst-Agents des Dienstes mit dem folgenden Ausdruck abrufen:

${google_project_service_identity.default.email}

REST

Suchen Sie das E-Mail-Adressformat des Dienst-Agents, falls Sie dies noch nicht getan haben. Dieses Format ist in der Referenz zum Dienst-Agent dokumentiert.
Ersetzen Sie alle Platzhalter in der E-Mail-Adresse durch das entsprechende Projekt, den Ordner oder die Organisationsnummer.

Dem Dienst-Agent eine Rolle zuweisen

Wenn Sie die E-Mail-Adresse des Dienst-Agents gefunden haben, können Sie ihr eine Rolle zuweisen, wie Sie sie auch einem anderen Hauptkonto zuweisen würden.

Console

Öffnen Sie in der Google Cloud Console die Seite IAM.

IAM aufrufen
Wählen Sie ein Projekt, einen Ordner oder eine Organisation aus.
Klicken Sie auf Zugriff erlauben und geben Sie dann die E-Mail-Adresse des Dienst-Agents ein.
Wählen Sie eine Rolle aus der Drop-down-Liste aus.
Optional: Fügen Sie der Rolle eine Bedingung hinzu.
Klicken Sie auf Speichern. Dem Dienst-Agent wird die Rolle für die Ressource zugewiesen.

gcloud

Mit dem Befehl add-iam-policy-binding können Sie einem Hauptkonto schnell eine Rolle zuweisen.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

RESOURCE_TYPE: Der Ressourcentyp, für den Sie den Zugriff verwalten möchten. Verwenden Sie projects, resource-manager folders oder organizations.
RESOURCE_ID: Ihr Google Cloud-Projekt, Ihr Ordner oder Ihre Organisations-ID. Projekt-IDs sind alphanumerisch, z. B. my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
PRINCIPAL: Eine Kennung für das Hauptkonto bzw. Mitglied, die normalerweise die folgende Form hat: PRINCIPAL_TYPE:ID. Beispiel: user:my-user@example.com. Eine vollständige Liste der für PRINCIPAL zulässigen Werte finden Sie in der Referenz zur Richtlinienbindung.

Beim Hauptkontotyp user muss der Domainname in der Kennung eine Google Workspace- oder Cloud Identity-Domain sein. Informationen zum Einrichten einer Cloud Identity-Domain finden Sie unter Cloud Identity – Übersicht.
ROLE_NAME: Der Name der Rolle, die Sie aufheben möchten. Verwenden Sie eines der folgenden Formate:
- Vordefinierte Rollen: roles/SERVICE.IDENTIFIER
- Benutzerdefinierte Rollen auf Projektebene: projects/PROJECT_ID/roles/IDENTIFIER
- Benutzerdefinierte Rollen auf Organisationsebene: organizations/ORG_ID/roles/IDENTIFIER
Eine Liste der vordefinierten Rollen finden Sie unter Informationen zu Rollen.
CONDITION: Die Bedingung, die der Rollenbindung hinzugefügt werden soll. Wenn Sie keine Bedingung hinzufügen möchten, verwenden Sie den Wert None. Weitere Informationen zu Bedingungen finden Sie in der Übersicht der Bedingungen.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

Die Antwort enthält die aktualisierte IAM-Richtlinie:

Terraform

# Grant the AI Platform Custom Code Service Account the Vertex AI Custom
# Code Service Agent role (roles/aiplatform.customCodeServiceAgent)
resource "google_project_iam_member" "custom_code" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.customCodeServiceAgent"
  member  = "serviceAccount:service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com"
}

# Grant the primary aiplatform.googleapis.com service agent (AI Platform
# Service Agent) the Vertex AI Service Agent role
# (roles/aiplatform.serviceAgent)
resource "google_project_iam_member" "primary" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.serviceAgent"
  member  = "serviceAccount:${google_project_service_identity.default.email}"
}

REST

Verwenden Sie das Read-Modify-Write-Muster, um eine Rolle mit der REST API zuzuweisen:

Lesen Sie die aktuelle Zulassungsrichtlinie, indem Sie getIamPolicy() aufrufen.

Die Methode getIamPolicy der Resource Manager API ruft die „allow”-Richtlinie eines Projekts, des Ordners oder der Organisation ab.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- API_VERSION: Die zu verwendende API-Version. Verwenden Sie v1 für Projekte und Organisationen. Verwenden Sie v2 für Ordner.
- RESOURCE_TYPE: Der Ressourcentyp, dessen Richtlinie Sie verwalten möchten. Verwenden Sie den Wert projects, folders oder organizations.
- RESOURCE_ID: Die ID Ihres Google Cloud-Projekts, Ihrer Organisation oder Ihres Ordners. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
- POLICY_VERSION: Die Richtlinienversion, die zurückgegeben werden soll. Anfragen sollten die neueste Richtlinienversion angeben. Diese ist Richtlinienversion 3. Weitere Informationen finden Sie unter Richtlinienversion beim Abrufen einer Richtlinie festlegen.
HTTP-Methode und URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
JSON-Text anfordern:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (Browser)

Kopieren Sie den Anfragetext und öffnen Sie die Referenzseite für Methoden. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Fügen Sie den Anfragetext in dieses Tool ein, füllen Sie alle Pflichtfelder aus und klicken Sie auf Ausführen.

Die Antwort enthält die Zulassungsrichtlinie des Projekts. Beispiel:
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:owner@example.com"
      ]
    }
  ]
}
```
Zulassungsrichtlinie der Ressource entweder mithilfe eines Texteditors oder programmatisch bearbeiten, um Hauptkonten oder Rollenbindungen hinzuzufügen oder zu entfernen. Sie können beispielsweise eine neue Rollenbindung hinzufügen, eine vorhandene Rollenbindung entfernen oder Hauptkonten zu einer vorhandenen Rollenbindung hinzufügen oder daraus entfernen.
Schreiben Sie die aktualisierte Zulassungsrichtlinie durch Aufrufen von setIamPolicy().

Die Methode setIamPolicy der Resource Manager API legt die Richtlinie in der Anfrage als neue „allow”-Richtlinie für das Projekt, den Ordner oder die Organisation fest.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:
- API_VERSION: Die zu verwendende API-Version. Verwenden Sie v1 für Projekte und Organisationen. Verwenden Sie v2 für Ordner.
- RESOURCE_TYPE: Der Ressourcentyp, dessen Richtlinie Sie verwalten möchten. Verwenden Sie den Wert projects, folders oder organizations.
- RESOURCE_ID: Die ID Ihres Google Cloud-Projekts, Ihrer Organisation oder Ihres Ordners. Projekt-IDs sind alphanumerische Strings, wie my-project. Ordner- und Organisations-IDs sind numerisch, z. B. 123456789012.
- POLICY: Eine JSON-Darstellung der Richtlinie, die Sie festlegen möchten. Weitere Informationen zum Format einer Richtlinie finden Sie in der Richtlinienreferenz.
HTTP-Methode und URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
JSON-Text anfordern:
```
{
  "policy": POLICY
}
```
Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:
curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
PowerShell (Windows)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (Browser)

Kopieren Sie den Anfragetext und öffnen Sie die Referenzseite für Methoden. Der API Explorer wird rechts auf der Seite geöffnet. Sie können mit diesem Tool interagieren, um Anfragen zu senden. Fügen Sie den Anfragetext in dieses Tool ein, füllen Sie alle Pflichtfelder aus und klicken Sie auf Ausführen.

Die Antwort enthält die aktualisierte Zulassungsrichtlinie:

Hinweis: Wenn Sie Richtlinien als Code behandeln und in einem Versionsverwaltungssystem speichern, sollten Sie die Richtlinie speichern, die zurückgegeben wird, und nicht die Richtlinie, die Sie in der Anfrage gesendet haben.

Nächste Schritte

Liste aller Dienst-Agents ansehen
Weitere Möglichkeiten zur Zuweisung von Rollen für Hauptkonten
Nutzerverwaltete Dienstkonten erstellen, die als Identitäten für Ihre Arbeitslasten fungieren können
Weitere Informationen zu Best Practices für die Verwendung von Terraform in Google Cloud
Alle Google Cloud-Terraform-Beispiele

Rollen für Dienst-Agents erstellen und zuweisen

Hinweise

Erforderliche Rollen

Erforderliche Berechtigungen

Zu erstellende Dienst-Agents identifizieren

Console

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Erstellen eines Trigger-Dienst-Agents

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Dienst-Agents Rollen zuweisen

E-Mail-Adresse des Dienst-Agents suchen

gcloud

Terraform

REST

Dem Dienst-Agent eine Rolle zuweisen

Console

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

APIs Explorer (Browser)

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

APIs Explorer (Browser)

Nächste Schritte