Diese Seite wurde von der Cloud Translation API übersetzt.

API verwenden – Empfehlungen

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

Eine typische empfohlene Interaktion mit der Recommender API ist:

Listen Sie die Empfehlungen für ein bestimmtes Projekt auf.
Markieren Sie eine Empfehlung, die Sie anwenden möchten, als claimed, oder markieren Sie eine Empfehlung, die Sie nicht anwenden möchten, als dismissed.
Wenden Sie die Empfehlung an. Dies kann automatisch mit Active Assist in der Google Cloud Console oder manuell mit Google Cloud CLI-Befehlen, REST API-Aufrufen oder anderen Tools erfolgen.

Wenn Sie die Empfehlung manuell anwenden, sind die von Ihnen 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 des Werts des Feldes resource im Array OperationsGroup der zurückgegebenen Recommendation-Entität. Dieses Feld hat das folgende Format:
```
//API_NAME/RESOURCE_PATH
```
Beispiel:
```
//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1
```
Markieren Sie die Empfehlung als succeeded oder failed.

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

Informationen zum Ändern des Status von Empfehlungen in derGoogle Cloud -Konsole finden Sie in der Dokumentation zu Active Assist oder zum 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 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 Recommender finden Sie eine Tabelle mit Links zu Informationen zu den einzelnen Recommender, einschließlich unterstützter Standorte und Recommender-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.
Für jeden Recommender sind bestimmte Berechtigungen erforderlich. 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 aktuellen Größenempfehlungen für VM-Instanzen 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 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. Der Empfehlungsdienst kann die Empfehlung weiterhin mit neueren Inhalten aktualisieren.

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

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