API verwenden – Statistiken

Auf dieser Seite erfahren Sie, wie Sie Insights in Recommender mit gcloud-Befehlen oder der REST-API anzeigen und verwalten.

Eine typische Interaktion zwischen dem Insight und der Recommender API ist:

Insights auflisten, die derzeit für einen bestimmten Insight-Typ verfügbar sind
Insight, für den Sie Maßnahmen ergreifen möchten, als angenommen markieren.

Informationen zum Ändern des Status von Insights in der Google Cloud Console finden Sie in der Dokumentation zum Empfehlungs-Hub oder unter dem entsprechenden Insight-Typ.

Standardprojekt festlegen

Legen Sie das Standardprojekt fest, falls Sie dies noch nicht getan haben:

gcloud config set project PROJECT_ID

Dabei entspricht PROJECT_ID der ID des Projekts.

Umgebungsvariablen festlegen

Legen Sie Umgebungsvariablen für Recommender-Interaktionen fest:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

wobei

TARGET_PROJECT_ID ist das Projekt, dessen Insights Sie auflisten möchten. Dies kann ein anderes Projekt als Ihr aktuelles Projekt sein.
- Für gcloud-Befehle müssen Sie die Projekt-ID verwenden
- Für API-Anfragen können Sie die Projektnummer oder Projekt-ID verwenden. Projektnummer wird empfohlen.
Die Projektnummer wird in Antworten der API und der gcloud-Befehle zurückgegeben.
LOCATION_ID der Google Cloud-Standort ist, an dem sich die Ressourcen für Insights befinden (z. B. global oder us-central1-a).
INSIGHT_TYPE_ID ist die voll qualifizierte Insight-Typ-ID (z. B. google.iam.policy.Insight).

Unter Insight-Typen finden Sie eine Tabelle mit Links zu den einzelnen Insight-Typen, einschließlich der unterstützten Standorte und Insight-Typ-IDs.

Berechtigungen festlegen

Sie müssen über die erforderlichen Berechtigungen verfügen, um auf Insights im Zielprojekt zuzugreifen.

Anfragesteller, die ihrer Anfrage ein Abrechnungsprojekt hinzufügen. Das in der Anfrage verwendete Projekt muss einwandfrei sein. Außerdem muss der Nutzer im Projekt eine Rolle mit der Berechtigung serviceusage.services.use haben. Die Rolle Dienstnutzungsnutzer enthält die erforderliche Berechtigung.
Jeder Statistiktyp erfordert bestimmte Berechtigungen. Unter Insight-Typen finden Sie eine Tabelle mit Links zu den einzelnen Insight-Typen, einschließlich der erforderlichen Berechtigungen.

Insights auflisten

So listen Sie Insights im Zielprojekt auf:

gcloud

Geben Sie Folgendes ein:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

Dabei ist FORMAT ein unterstütztes gcloud-Ausgabeformat (z. B. json).

Beispiel:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

REST

Geben Sie Folgendes ein:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights"

Beispiel:

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/insightTypes/google.iam.policy.Insight/insights"

Dieser Vorgang gibt die aktuellen IAM-Richtlinien-Insights im Zielprojekt als Liste von Insight-Entitäten im angegebenen Format aus.

Die Ausgabe sieht etwa so aus:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

Die zurückgegebenen Insights umfassen die folgenden Felder:

Ein name-Feld im folgenden Format:

projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

Dabei gibt INSIGHT_ID die Insights eindeutig an

Ein etag-Feld, das dem aktuellen Insight-Status zugeordnet ist.

Wenn Sie mit nachfolgenden gcloud-Befehlen oder REST API-Aufrufen auf einen Insight verweisen, verweisen Sie sowohl auf die Insight-ID als auch auf das etag. Dadurch werden alle Vorgänge nur dann ausgeführt, wenn der Insight seit dem letzten Aufruf nicht geändert wurde.

Insight als angenommen markieren

Sie können einen Insight als angenommen kennzeichnen, um anzugeben, dass Sie mit einer zugehörigen Ressource basierend auf den Informationen, die Sie gewonnen haben, eine Aktion ausgeführt haben oder ausführen möchten. Wenn ein Insight angenommen wird, wird Ihr Nutzername als der Ersteller für die Insight zugewiesen und Recommender aktualisiert die Insight nicht mit neueren Inhalten.

So markieren Sie einen Insight als angenommen:

gcloud

Passende Sucheingabe

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

wobei

INSIGHT_ID ist die ID eines Insights, der aus einem vorherigen Aufruf abgerufen wurde, um Insights aufzulisten
etag ist das zurückgegebene etag, das den Insight-Status darstellt.
STATE_METADATA sind optionale Metadaten zum Vorgang. Geben Sie die Metadaten als kommagetrennte Liste von KEY=VALUE-Paaren an.

Beispiel:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Geben Sie Folgendes ein:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

wobei

INSIGHT_ID ist die ID eines Insights, der aus einem vorherigen Aufruf abgerufen wurde, um Insights aufzulisten
etag ist das zurückgegebene etag, das den Insight-Status darstellt.
STATE_METADATA ist ein optionales Feld mit zusätzlichen Metadaten zum Vorgang. Geben Sie die Metadaten als key:value-Paare an.

Beispiel:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Dieser Vorgang gibt die Entität Insight im angegebenen Format zurück, nachdem der Vorgang abgeschlossen wurde.

Die Ausgabe sieht etwa so aus:

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

Beachten Sie, dass sich der Wert des Felds state in ACCEPTED geändert hat.