API verwenden – Statistiken

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

Hinweis: Einige Recommender unterstützen nicht die Verwendung der REST-API oder der gcloud CLI, um Empfehlungen und Erkenntnisse anzuzeigen und zu verwalten. Weitere Informationen zu Recommender und unterstützten Clients finden Sie unter Recommender.

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

• Statistiken für ein bestimmtes Projekt auflisten
• 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

Dabei gilt:

• 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.

Hinweis: Wenn Sie in Ihrer Anfrage den x-goog-user-project Header oder den userProject Abfragestringparameter verwenden, benötigen Sie für die Projekt-ID, die Sie angeben, die Berechtigung serviceusage.services.use, zusätzlich zu den normalen IAM-Berechtigungen, die zum Senden der Anfrage erforderlich sind.

Insights auflisten

Wie auf dem Tab gcloud Beta zu sehen ist, können Sie alle Empfehlungen Ihres Projekts auflisten, ohne einen Ort und einen Recommender angeben zu müssen. Dieses Feature befindet sich im Vorschaumodus.

Für die Google Analytics-Funktion müssen Sie ein Projekt, einen Standort und einen Recommender angeben. Weitere Informationen finden Sie auf dem Tab gcloud.

gcloud Beta

Vorschau

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Geben Sie Folgendes ein:

gcloud beta recommender insights list \
    --project=${PROJECT} \
    --format=FORMAT

wobei FORMAT ein unterstütztes Google Cloud CLI-Ausgabeformat ist, z. B. json.

Beispiel:

gcloud beta recommender insights list \
    --project=example-project \
    --format=json

Hinweis: Im Unterschied zur folgenden Ausgabe für die Tabs gcloud und REST, die auf Statistiken für einen Speicherort und Recommender beschränkt sind, enthält die Ausgabe alle Statistiken für das Projekt.

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:[e-mail]",
      "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

Geben Sie Folgendes ein:

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

Dabei gilt:

• 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

Dabei gilt:

• 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": "[e-mail]",
  "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.