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:

  • Listenempfehlungen, die derzeit für einen bestimmten Recommender verfügbar sind
  • Markieren Sie eine Empfehlung, die Sie als beansprucht anwenden möchten, oder markieren Sie eine Empfehlung, die Sie nicht anwenden möchten, als abgelehnt
  • Wenden Sie die Empfehlung mit gcloud-Befehlen oder REST API-Aufrufen an, die für den Ressourcentyp spezifisch sind (z. B. IAM-Rollen oder Compute Engine-VM-Instanzen).
  • Die Empfehlung als erfolgreich oder fehlgeschlagen markieren

Beachten Sie, dass nur Empfehlungen, die über die API abgerufen werden, über die API oder den BigQuery-Export interagieren können.

Informationen zum Ändern des Status von Empfehlungen in der Google Cloud Console finden Sie in der Dokumentation zu Recommendation Hub 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 der Google Cloud-Standort ist, an dem sich die Ressourcen für Empfehlungen befinden (z. B. global oder us-central1-a).

  • RECOMMENDER_ID die vollständig qualifizierte Empfehlungs-ID ist (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 benötigt bestimmte Berechtigungen. Unter Recommender finden Sie eine Tabelle mit verlinkten Informationen über die einzelnen Recommender, einschließlich der erforderlichen Berechtigungen.

Empfehlungen auflisten

So listen Sie Empfehlungen im Zielprojekt auf:

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

Empfehlung als beansprucht oder abgelehnt markieren

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

So markieren Sie eine Empfehlung als "Beansprucht" oder "verworfen":

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

Wobei:

  • STATE_CHANGE ist der Status, den Sie einer Empfehlung markieren möchten. Gültige Werte sind:
    • mark-claimed, um die Empfehlung als beansprucht zu markieren
    • mark-dismissed, um die Empfehlung als abgelehnt zu markieren.
  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • 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-claimed \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

Dabei gilt:

  • STATE_CHANGE ist der Status, den Sie einer Empfehlung markieren möchten. Gültige Werte sind:
    • mark-claimed, um die Empfehlung als beansprucht zu markieren
    • mark-dismissed, um die Empfehlung als abgelehnt zu markieren.
  • RECOMMENDATION_ID ist die ID einer Empfehlung, die Sie von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • 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:markClaimed \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Dieser Vorgang gibt die Entität Recommendation 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": "\"5e3a63cccf1e0964\"",
  "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": "CLAIMED"
  }
}

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

Empfehlungen anwenden

Nachdem Sie eine Empfehlung als beansprucht markiert haben, können Sie die Empfehlung mit gcloud-Befehlen oder REST API-Aufrufen anwenden, die für den Ressourcentyp spezifisch sind.

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 des Werts des Feldes resource im Array OperationsGroup 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"

Status einer Empfehlung ändern

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

So markieren Sie eine Empfehlung als erfolgreich:

gcloud

Geben Sie Folgendes ein:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Wo

  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten. Gültige Werte sind:
    • mark-succeeded, um die Empfehlung als erfolgreich zu markieren.
    • mark-failed, um die Empfehlung als fehlgeschlagen zu markieren.
  • STATE_METADATA sind optionale Metadaten zum Vorgang. Geben Sie die Metadaten als eine durch Kommas getrennte 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 von einem vorherigen Aufruf abgerufen haben, um Empfehlungen für Listen abzurufen
  • STATE_CHANGE ist die Änderung, die Sie an einer Empfehlung vornehmen möchten. Gültige Werte sind:
    • 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 Entität Recommendation 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.