API verwenden – Empfehlungen

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

Eine typische empfohlene Interaktion mit der Recommender API ist:

  1. Listen Sie die Empfehlungen auf für ein bestimmtes Projekt.

  2. Markieren Sie eine Empfehlung, die Sie anwenden möchten, als claimed, oder markieren Sie eine Empfehlung, die Sie nicht anwenden möchten, als dismissed.

  3. Wenden Sie die Empfehlung an. Sie können dies automatisch mit Active Assist in der Google Cloud Console oder manuell mit den Google Cloud CLI-Befehlen, REST API-Aufrufen oder anderen Tools tun.

    Wenn Sie die Empfehlung manuell anwenden, sind die verwendeten Befehle oder Aufrufe für den Ressourcentyp spezifisch. Wenn Sie beispielsweise die Größe einer VM-Instanz als Reaktion auf eine Empfehlung des Größen-Recommenders für die VM-Instanz ändern möchten, verwenden Sie Compute Engine gcloud Befehle oder Aufrufe der Compute Engine REST API.

    Wenn Sie diese Vorgänge ausführen, identifizieren Sie die Zielressource mithilfe von dem Wert des Feldes resource im Array OperationsGroup in der zurückgegebenen Recommendation Entität. Dieses Feld hat folgendes Format:

    //API_NAME/RESOURCE_PATH

    Beispiel:

    //compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1

  4. Markieren Sie die Empfehlung als succeeded oder failed.

Beachten Sie, dass nur Empfehlungen, die über die API abgerufen wurden, über die API oder BigQuery-Exportbearbeitet werden können.

Informationen zum Ändern des Status von Empfehlungen in der Google Cloud Console finden Sie in der Dokumentation zu Active Assist oder für den entsprechenden Recommender.

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
RECOMMENDER=RECOMMENDER_ID

Dabei gilt:

  • TARGET_PROJECT_ID ist das Projekt, dessen Empfehlungen 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 ist der Google Cloud Standort, an dem sich die mit den Empfehlungen verknüpften Ressourcen befinden (z. B. global oder us-central1-a).

  • RECOMMENDER_ID ist die vollständig qualifizierte Empfehlungs-ID (z. B. google.compute.instance.MachineTypeRecommender).

Unter Empfehlungen finden Sie eine Tabelle mit verlinkten Informationen zu den einzelnen Empfehlungen, einschließlich unterstützter Standorte und Empfehlungs-IDs.

Berechtigungen festlegen

Sie müssen über die erforderlichen Berechtigungen verfügen, um auf Empfehlungen 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 Recommender erfordert bestimmte Berechtigungen. Unter Recommender finden Sie eine Tabelle mit verlinkten Informationen über die einzelnen Recommender, einschließlich der erforderlichen Berechtigungen.

Empfehlungen 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

Geben Sie Folgendes ein:

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

wobei FORMAT ein unterstütztes gcloud-Ausgabeformat ist, z. B. json.

Beispiel:

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

gcloud

Geben Sie Folgendes ein:

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

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

Beispiel:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations"

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/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

Dieser Vorgang gibt die Größenempfehlungen für die aktuelle VM-Instanz im Zielprojekt als Liste von Recommendation Entitäten im angegebenen Format aus.

Die Ausgabe sieht etwa so aus:

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "test",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "valueMatcher": {
                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"
              }
            },
            {
              "action": "replace",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "value": "zones/us-central1-a/machineTypes/custom-2-5120"
            }
          ]
        }
      ]
    },
    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
    "etag": "\"280b34810bba8a1a\"",
    "lastRefreshTime": "2019-06-28T06:49:21Z",
    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "primaryImpact": { ... },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "recommenderSubtype": "CHANGE_MACHINE_TYPE"
  }
]

Die zurückgegebenen Empfehlungen umfassen die folgenden Felder:

  • Ein name-Feld im folgenden Format:

    projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

    Dabei identifiziert RECOMMENDATION_ID die Empfehlung eindeutig

  • Ein etag-Feld, das dem aktuellen Empfehlungsstatus zugeordnet ist.

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

Status einer Empfehlung ändern

Sie können eine Empfehlung als beansprucht markieren, um anzugeben, dass Sie die empfohlenen Änderungen auf die zugehörige Ressource anwenden möchten. Wenn eine Empfehlung beansprucht wird, wird Ihr Nutzername als der Ersteller für die Empfehlung zugewiesen und Recommender aktualisiert die Empfehlung nicht mit neueren Inhalten.

Sie können eine Empfehlung als abgelehnt markieren, um anzugeben, dass Sie die empfohlenen Änderungen nicht auf die zugehörige Ressource anwenden möchten oder die Empfehlung nicht mehr sehen möchten. Verworfene Empfehlungen werden nicht mehr als AKTIVE Empfehlungen angezeigt. Recommender aktualisiert die Empfehlung möglicherweise weiterhin mit neueren Inhalten.

Nachdem Sie eine Empfehlung übernommen haben, können Sie sie als erfolgreich oder fehlgeschlagen markieren.

So ändern Sie den Status einer Empfehlung:

gcloud

Geben Sie Folgendes ein:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=ETAG \
    --state-metadata=STATE_METADATA \
    --format=FORMAT

Wo

  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten. Gültige Werte sind:
    • mark-claimed, um die Empfehlung als beansprucht zu markieren.
    • mark-dismissed, um die Empfehlung als abgelehnt zu markieren.
    • mark-succeeded, um die Empfehlung als erfolgreich zu markieren.
    • mark-failed, um die Empfehlung als fehlgeschlagen zu markieren.
  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie bei einem vorherigen Aufruf zum Auflisten von Empfehlungen abgerufen haben.
  • ETAG ist das zurückgegebene etag, das den Empfehlungsstatus darstellt.
  • STATE_METADATA sind optionale Metadaten zum Vorgang. Geben Sie die Metadaten als kommagetrennte Liste von KEY=VALUE Paaren an. Diese Option ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

Beispiel:

gcloud recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "ETAG"
  "stateMetadata": STATE_METADATA
}
EOM

Dabei gilt:

  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie bei einem vorherigen Aufruf zum Auflisten von Empfehlungen abgerufen haben.
  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten. Gültige Werte sind:
    • markClaimed, um die Empfehlung als beansprucht zu markieren.
    • markDismissed, um die Empfehlung als abgelehnt zu markieren.
    • markSucceeded, um die Empfehlung als erfolgreich zu markieren.
    • markFailed, um die Empfehlung als fehlgeschlagen zu markieren.
  • ETAG ist das zurückgegebene etag, das den Empfehlungsstatus darstellt.
  • STATE_METADATA ist ein optionales Feld mit zusätzlichen Metadaten zum Vorgang. Geben Sie die Metadaten als key:value-Paare an. Dieses Feld ist verfügbar, wenn Sie eine Empfehlung als beansprucht, erfolgreich oder fehlgeschlagen markieren.

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/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

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

Die Ausgabe sieht etwa so aus:

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e053c\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

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