Bereitstellungssteuerungen konfigurieren

Mit Steuerelementen für die Bereitstellung (auch als Steuerelemente bezeichnet) wird das Standardverhalten bei der Bereitstellung einer Anfrage geändert, wenn Ergebnisse zurückgegeben werden. Die Auslieferungssteuerung erfolgt auf Datenspeicherebene.

Mit Steuerelementen können Sie beispielsweise Ergebnisse hoch- und herabstufen, Einträge aus zurückgegebenen Ergebnissen filtern, Strings als Synonyme miteinander verknüpfen oder Ergebnisse zu bestimmten URIs weiterleiten.

Bereitstellungseinstellungen

Wenn Sie die Ergebnisse einer Anfrage ändern möchten, müssen Sie zuerst ein Steuerelement für die Bereitstellung erstellen. Hängen Sie dieses Steuerelement dann an die Bereitstellungskonfiguration einer App an. Eine Bereitstellungskonfiguration konfiguriert Metadaten, die zum Generieren von Ergebnissen zur Bereitstellungszeit verwendet werden, z. B. Suchergebnisse oder Antworten. Eine Bereitstellungseinstellung wirkt sich nur auf Anfragen aus, die von der App bereitgestellt werden, wenn die Einstellung an die Bereitstellungskonfiguration der App angehängt ist.

Für einige Einstellungen, z. B. für die Steuerung von Steigerungen, sind Datenstores erforderlich. Wenn ein Datenspeicher aus einer App entfernt wird, werden alle datenspeicherabhängigen Steuerelemente ebenfalls aus dieser App entfernt und deaktiviert, aber nicht gelöscht.

Typen von Bereitstellungseinstellungen

Folgende Bereitstellungssteuerungen sind verfügbar:

Steuerung Beschreibung Verfügbar für
Boost-Steuerung Ändert die Reihenfolge der zurückgegebenen Ergebnisse Suchanwendungen mit Datenspeichern, die ein Schema unterstützen, z. B. Datenspeicher mit strukturierten Daten oder unstrukturierten Daten mit Metadaten
Filtersteuerung Entfernt Einträge aus den zurückgegebenen Ergebnissen Suchanwendungen mit Datenspeichern, die ein Schema unterstützen, z. B. Datenspeicher mit strukturierten Daten oder unstrukturierten Daten mit Metadaten
Synonymsteuerelement Abfragen miteinander verknüpfen Suchanwendungen mit strukturierten oder unstrukturierten Datenspeichern
Weiterleitungssteuerung Weiterleitungen zu einem angegebenen URI Alle Such-Apps
Einstellung für Hochstufung Bewirbt einen bestimmten Link für eine Anfrage Suchanwendungen mit strukturierten oder unstrukturierten Datenspeichern

Bedingungen

Beim Erstellen eines Steuerelements können Sie optional eine Bedingung definieren, die bestimmt, wann das Steuerelement angewendet wird. Bedingungen werden mit Bedingungsfeldern definiert. Folgende Felder für Bedingungen sind verfügbar:

  • queryTerms: Eine optionale Steuerung, die bei der Suche nach bestimmten Anfragen angewendet wird. Wenn die Bedingung queryTerms verwendet wird, wird die Steuerung angewendet, wenn der Wert von queryTerms mit einem Begriff in SearchRequest.query übereinstimmt. Suchbegriffe können nur verwendet werden, wenn Control.searchUseCase auf SOLUTION_TYPE_SEARCH festgelegt ist. Für ein einzelnes Control.condition können bis zu 10 verschiedene queryTerms angegeben werden. Wenn keine Suchbegriffe angegeben sind, wird das Feld queryTerms ignoriert.

    Damit Sie ein Promote-Steuerelement erstellen können, müssen Sie das Feld queryTerms mit fullMatch auf true oder false festlegen.

  • activeTimeRange: Eine optionale Steuerung, die angewendet wird, wenn eine Anfrage innerhalb eines bestimmten Zeitraums erfolgt. Sie prüft, ob die Zeit, zu der eine Anfrage empfangen wurde, zwischen activeTimeRange.startTime und activeTimeRange.endTime liegt. Für eine einzelne Control.condition können bis zu 10 activeTimeRange-Bereiche angegeben werden. Wenn das Feld activeTimeRange nicht angegeben ist, wird es ignoriert.

Wenn für eine Steuerung mehrere Bedingungen angegeben sind, wird die Steuerung auf die Suchanfrage angewendet, wenn beide Bedingungstypen erfüllt sind. Wenn mehrere Werte für dieselbe Bedingung angegeben sind, muss nur einer der Werte übereinstimmen, damit die Bedingung erfüllt ist.

Betrachten Sie beispielsweise die folgende Bedingung mit zwei angegebenen Suchbegriffen:

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

Die Bedingung wird für eine Anfrage mit SearchRequest.query="gShoe" oder eine Anfrage mit SearchRequest.query="gBoot" erfüllt, aber nicht für SearchRequest.query="gSandal" oder einen anderen String.

Wenn keine Bedingungen angegeben sind, wird die Einstellung immer angewendet.

Weitere Informationen finden Sie in der API-Referenz im Feld Condition.

Bereitstellungssteuerelemente für Kampagnen mit Steigerung erstellen und anhängen

Eine Kontrollgruppe für die Bereitstellung von Kampagnen mit Steigerung ist eine Kontrollgruppe mit einer boostAction.

So erstellen Sie eine Kontrollgruppe für die Steigerung der Bereitstellung:

Details zu den Feldern finden Sie in der engines.controls API-Referenz und der engines.controls.create API-Referenz.

  1. Suchen Sie Ihre App-ID. Wenn Sie Ihre App-ID bereits haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und entnehmen Sie die App-ID der Spalte ID.

  2. Führen Sie die folgenden curl-Befehle aus, um die Kontrollvariablen zu erstellen.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: Die ID der App.
    • CONTROL_ID: eine eindeutige Kennung für die Kontrollgruppe. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der für Menschen lesbare Name der Kontrollvariablen. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden sollte. Muss ein UTF-8-codierter String mit einer Länge von [1,128] sein.
    • USE_CASE: muss entweder SEARCH_USE_CASE_SEARCH oder SEARCH_USE_CASE_BROWSE sein. Wenn SEARCH_USE_CASE_BROWSE angegeben ist, kann Condition.queryTerms nicht in der Bedingung verwendet werden.
    • CONDITION: Ein optionales Feld, das definiert, wann die Kontrollgruppe angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld maximal drei durch Leerzeichen getrennte Begriffe enthalten.
      • FULL_MATCH: Ein boolescher Wert, der angibt, ob die Suchanfrage genau mit dem Suchbegriff übereinstimmen muss. Wenn der Wert auf true festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn der Wert auf false festgelegt ist, muss SearchRequest.query den Wert queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der den Beginn eines Zeitbereichs angibt.
      • END_TIMESTAMP: Ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der das Ende eines Zeitbereichs angibt.
    • BOOST_VALUE: eine Gleitkommazahl im Bereich [-1,1]. Wenn der Wert negativ ist, werden die Ergebnisse herabgestuft (sie werden weiter unten in den Ergebnissen angezeigt). Wenn der Wert positiv ist, werden die Ergebnisse höher in den Suchergebnissen platziert. Weitere Informationen finden Sie unter boostAction.
    • FILTER: Ein String, der die Anforderungen angibt, die das Dokument erfüllen muss. Wenn das Dokument alle Anforderungen erfüllt, wird die Steigerung angewendet. Andernfalls ändert sich nichts. Wenn dieses Feld leer ist, wird der Boost auf alle Dokumente im Datenspeicher angewendet. Informationen zur Filtersyntax finden Sie unter Filterausdruckssyntax. Hinweis: Das Dokumentfeld title kann nicht gefiltert werden.
    • DATA_STORE_RESOURCE_PATH: Der vollständige Ressourcenpfad des Datenspeichers, dessen Dokumente durch diese Steuerungseinstellung gefördert werden sollen. Der vollständige Ressourcenpfad hat das Format projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Dieser Datenspeicher muss an die im Antrag angegebene Engine angehängt werden.

  3. Hängen Sie die Steuerung mithilfe der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Ersetzen Sie BOOST_ID_N durch die Kontroll-IDs, die Sie im vorherigen Schritt erstellt haben.

Filterbereitstellungssteuerelemente erstellen und anhängen

Ein Filter-Serving-Kontrollsegment wird als Kontrollsegment mit einem filterAction definiert.

So erstellen Sie eine Kontrollgruppe für Filter:

Details zu den Feldern finden Sie in der engines.controls API-Referenz und der engines.controls.create API-Referenz.

  1. Suchen Sie Ihre App-ID. Wenn Sie Ihre App-ID bereits haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und entnehmen Sie die App-ID der Spalte ID.

  2. Führen Sie die folgenden curl-Befehle aus, um die Kontrollvariablen zu erstellen.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: Die ID der App.
    • CONTROL_ID: eine eindeutige Kennung für die Kontrollgruppe. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der für Menschen lesbare Name der Kontrollvariablen. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden sollte. Muss ein UTF-8-codierter String mit einer Länge von [1,128] sein.
    • USE_CASE: muss entweder SEARCH_USE_CASE_SEARCH oder SEARCH_USE_CASE_BROWSE sein. Wenn SEARCH_USE_CASE_BROWSE angegeben ist, kann Condition.queryTerms nicht in der Bedingung verwendet werden.
    • CONDITION: Ein optionales Feld, das definiert, wann die Kontrollgruppe angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld maximal drei durch Leerzeichen getrennte Begriffe enthalten.
      • FULL_MATCH: Ein boolescher Wert, der angibt, ob die Suchanfrage genau mit dem Suchbegriff übereinstimmen muss. Wenn der Wert auf true festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn der Wert auf false festgelegt ist, muss SearchRequest.query den Wert queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der den Beginn eines Zeitbereichs angibt.
      • END_TIMESTAMP: Ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der das Ende eines Zeitbereichs angibt.
    • FILTER: Ein String, der die Anforderungen angibt, die das Dokument erfüllen muss. Wenn das Dokument alle Anforderungen erfüllt, wird es in den Ergebnissen zurückgegeben. Andernfalls wird das Dokument nicht in den Ergebnissen angezeigt. Informationen zur Filtersyntax finden Sie unter Filterausdruckssyntax. Weitere Informationen finden Sie unter filterAction. Hinweis: Das Dokumentfeld title kann nicht gefiltert werden.

  3. Hängen Sie die Steuerung mithilfe der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Ersetzen Sie FILTER_ID_N durch die Kontroll-IDs, die Sie im vorherigen Schritt erstellt haben.

Synonyme-Bereitstellungssteuerelemente erstellen und anhängen

Ein Steuerelement für die Bereitstellung von Synonymen ist ein Steuerelement mit einem synonymsAction.

Gehen Sie nach der folgenden Anleitung vor, um eine Steuerung für die Bereitstellung von Synonymen zu erstellen.

Details zu den Feldern finden Sie in der engines.controls API-Referenz und der engines.controls.create API-Referenz.

  1. Suchen Sie Ihre App-ID. Wenn Sie Ihre App-ID bereits haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und entnehmen Sie die App-ID der Spalte ID.

  2. Führen Sie die folgenden curl-Befehle aus, um die Kontrollvariablen zu erstellen.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: Die ID der App.
    • CONTROL_ID: eine eindeutige Kennung für die Kontrollgruppe. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der für Menschen lesbare Name der Kontrollvariablen. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden sollte. Muss ein UTF-8-codierter String mit einer Länge von [1,128] sein.
    • USE_CASE: muss entweder SEARCH_USE_CASE_SEARCH oder SEARCH_USE_CASE_BROWSE sein. Wenn SEARCH_USE_CASE_BROWSE angegeben ist, kann Condition.queryTerms nicht in der Bedingung verwendet werden.
    • CONDITION: Ein optionales Feld, das definiert, wann die Kontrollgruppe angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld maximal drei durch Leerzeichen getrennte Begriffe enthalten.
      • FULL_MATCH: Ein boolescher Wert, der angibt, ob die Suchanfrage genau mit dem Suchbegriff übereinstimmen muss. Wenn der Wert auf true festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn der Wert auf false festgelegt ist, muss SearchRequest.query den Wert queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der den Beginn eines Zeitbereichs angibt.
      • END_TIMESTAMP: Ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der das Ende eines Zeitbereichs angibt.
    • SYNONYMS_N: Eine Liste von Strings, die miteinander verknüpft sind, sodass für jeden String ähnliche Ergebnisse angezeigt werden. Es ist zwar wahrscheinlicher, dass Sie ähnliche Ergebnisse erhalten, aber wenn Sie nach jedem der Synonymeinträge suchen, erhalten Sie möglicherweise nicht alle relevanten Ergebnisse für alle zugehörigen Synonyme. Sie müssen mindestens zwei und können bis zu 100 Synonyme angeben. Jedes Synonym muss UTF-8-codiert und in Kleinbuchstaben sein. Doppelte Strings sind nicht zulässig. Sie können beispielsweise „Pixel“, „Android-Smartphone“ und „Google-Smartphone“ als Synonyme hinzufügen. Weitere Informationen finden Sie unter synonymsAction.

  3. Hängen Sie die Steuerung mithilfe der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Ersetzen Sie SYNONYMS_ID_N durch die Kontroll-IDs, die Sie im vorherigen Schritt erstellt haben.

Steuerelemente für die Weiterleitungsbereitstellung erstellen und anhängen

Mit einem Steuerelement für die Weiterleitung können Nutzer zu einem angegebenen URI weitergeleitet werden. Umleitungssteuerungen werden als Steuerung mit einem redirectAction definiert.

So erstellen Sie ein Steuerelement für die Bereitstellung von Weiterleitungen:

Details zu den Feldern finden Sie in der engines.controls API-Referenz und der engines.controls.create API-Referenz.

  1. Suchen Sie Ihre App-ID. Wenn Sie Ihre App-ID bereits haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und entnehmen Sie die App-ID der Spalte ID.

  2. Führen Sie die folgenden curl-Befehle aus, um die Kontrollvariablen zu erstellen.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: Die ID der App.
    • CONTROL_ID: eine eindeutige Kennung für die Kontrollgruppe. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der für Menschen lesbare Name der Kontrollvariablen. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden sollte. Muss ein UTF-8-codierter String mit einer Länge von [1,128] sein.
    • USE_CASE: muss entweder SEARCH_USE_CASE_SEARCH oder SEARCH_USE_CASE_BROWSE sein. Wenn SEARCH_USE_CASE_BROWSE angegeben ist, kann Condition.queryTerms nicht in der Bedingung verwendet werden.
    • CONDITION: Ein optionales Feld, das definiert, wann die Kontrollgruppe angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld maximal drei durch Leerzeichen getrennte Begriffe enthalten.
      • FULL_MATCH: Ein boolescher Wert, der angibt, ob die Suchanfrage genau mit dem Suchbegriff übereinstimmen muss. Wenn der Wert auf true festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn der Wert auf false festgelegt ist, muss SearchRequest.query den Wert queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der den Beginn eines Zeitbereichs angibt.
      • END_TIMESTAMP: Ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der das Ende eines Zeitbereichs angibt.
    • REDIRECT_URI_N: Ein URI, zu dem Sie weitergeleitet werden. Darf maximal 2.000 Zeichen lang sein. Wenn der Wert des Suchbegriffs beispielsweise „Support“ ist, können Sie eine Weiterleitung zu Ihrer Seite für technischen Support einrichten, anstatt Suchergebnisse für „Support“ zurückzugeben (oder nicht zurückzugeben). In diesem Beispiel lautet der Weiterleitungs-URI "https://www.example.com/support". Weitere Informationen finden Sie unter redirectAction.

  3. Hängen Sie die Steuerung mithilfe der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Ersetzen Sie REDIRECT_ID_N durch die Kontroll-IDs, die Sie im vorherigen Schritt erstellt haben.

Bereitstellungssteuerelemente für Werbung erstellen und anhängen

Mit einem Steuerelement für die Bereitstellung von Werbeinhalten können Sie einen Link als beworbenes Ergebnis anzeigen lassen. Diese Einstellung ist für Suchanwendungen mit strukturierten oder unstrukturierten Datenspeichern und für kombinierte Suchanwendungen verfügbar.

Damit die Promote-Steuerung wirksam wird, müssen Sie sie an die Serving-Konfiguration der App anhängen.

Promote-Steuerelemente werden mit einem promoteAction definiert.

Damit Sie ein Promote-Steuerelement erstellen können, müssen Sie das Feld queryTerms mit fullMatch auf true oder false festlegen.

So erstellen Sie ein Steuerelement für die Steuerung der Auslieferung von Werbeaktionen:

Details zu den Feldern finden Sie in der engines.controls API-Referenz und der engines.controls.create API-Referenz.

  1. Suchen Sie Ihre App-ID. Wenn Sie Ihre App-ID bereits haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und entnehmen Sie die App-ID der Spalte ID.

  2. Führen Sie die folgenden curl-Befehle aus, um die Kontrollvariablen zu erstellen.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH_TRUE|FALSE
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION",
  }
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: Die ID der App.
    • CONTROL_ID: eine eindeutige Kennung für die Kontrollgruppe. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der für Menschen lesbare Name der Kontrollvariablen. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden sollte. Muss ein UTF-8-codierter String mit einer Länge von [1,128] sein.
    • USE_CASE: muss entweder SEARCH_USE_CASE_SEARCH oder SEARCH_USE_CASE_BROWSE sein. Wenn SEARCH_USE_CASE_BROWSE angegeben ist, kann Condition.queryTerms nicht in der Bedingung verwendet werden.
    • Condition: Ein optionales Objekt, das definiert, wann die Kontrollgruppe angewendet werden soll. Enthält die folgenden Felder:
      • queryTerms:
        • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000].
        • FULL_MATCH_TRUE|FALSE: Ein boolescher Wert, der angibt, ob der Suchbegriff vollständig übereinstimmen muss.
      • activeTimeRange:
        • START_TIMESTAMP: ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der den Beginn eines Zeitbereichs angibt.
        • END_TIMESTAMP: Ein Zeitstempel im RFC 3339-UTC-Format „Zulu“, der das Ende eines Zeitbereichs angibt.
    • DATA_STORE_RESOURCE_PATH: Der vollständige Ressourcenpfad des Datenspeichers, dessen Suchergebnisse die beworbene URL enthalten. Der vollständige Ressourcenpfad hat das Format projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Dieser Datenspeicher muss an die im Antrag angegebene Engine angehängt werden.

    • DOCUMENT_RESOURCE_PATH: Ein Feld zum Angeben des Ressourcenpfads des Dokuments, das beworben werden soll. Sie müssen entweder die Dokument-ID im Feld DOCUMENT_RESOURCE_PATH, den URI im Feld URI oder beides angeben.

      Der vollständige Ressourcenpfad hat das Format projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.

    • TITLE: Ein Pflichtfeld, in dem Sie den Titel des zu bewerbenden Dokuments oder der zu bewerbenden Webseite angeben. Dieser Titel wird im Suchergebnis angezeigt.

    • URI: Ein Feld, in dem der URI angegeben wird, zu dem das Suchergebnis den Nutzer führt. Sie müssen entweder die Dokument-ID im Feld DOCUMENT_RESOURCE_PATH, den URI im Feld URI oder beides angeben.

    • URI_DESCRIPTION: Ein optionales Feld zur Beschreibung des URI, der im Suchergebnis angezeigt wird.

    Die Antwort enthält IDs für die Werbeaktion, die Sie Ihrer Such-App zuweisen müssen.

  3. Hängen Sie die Steuerung mithilfe der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an. Die Reihenfolge, in der Sie die promoteControlIds in der folgenden Anfrage anhängen, ist die Reihenfolge, in der die beworbenen Ergebnisse zurückgegeben werden.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    Ersetzen Sie PROMOTE_ID_N durch die Kontroll-IDs, die Sie im vorherigen Schritt erhalten haben.

Nächste Schritte