Bereitstellungssteuerung für die Suche konfigurieren

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

Mithilfe von Steuerelementen können Sie beispielsweise Ergebnisse hervorheben und unterdrücken, Einträge aus den zurückgegebenen Ergebnissen herausfiltern, Strings als Synonyme verknüpfen oder Ergebnisse an bestimmte URIs weiterleiten.

Auf dieser Seite werden die Einstellungen für die Auslieferung von Inhalten in Such-Apps beschrieben. Informationen zur Verwendung von Bereitstellungssteuerungen mit Medienempfehlungen finden Sie unter Bereitstellungskonfigurationen für Medien erstellen und verwalten.

Bereitstellungseinstellungen

Wenn Sie die Ergebnisse einer Anfrage ändern möchten, müssen Sie zuerst ein Steuerelement für die Bereitstellung erstellen. Fügen Sie das Steuerelement dann der Bereitstellungskonfiguration einer Such-App hinzu. In einer Bereitstellungskonfiguration werden Metadaten konfiguriert, die zum Generieren von Ergebnissen zum Zeitpunkt der Bereitstellung verwendet werden, z. B. Suchergebnisse oder Antworten. Eine Bereitstellungseinstellung wirkt sich nur auf Anfragen aus, die von der App gesendet werden, wenn die Einstellung mit der Bereitstellungskonfiguration der App verknüpft ist.

Einige Steuerelemente, z. B. die Steuerelemente für die Leistungssteigerung, sind von Datenspeichern abhängig. Wenn ein Datenspeicher aus einer App entfernt wird, werden auch alle datenspeicherabhängigen Steuerelemente aus dieser App entfernt und inaktiv, aber nicht gelöscht.

Arten von Bereitstellungseinstellungen

Folgende Arten von Bereitstellungssteuerungen sind verfügbar:

Steuerung Beschreibung Verfügbar für
Boost-Steuerung Ändert die Reihenfolge der zurückgegebenen Ergebnisse Such-Apps mit Datenspeichern, die ein Schema unterstützen, z. B. Datenspeicher mit strukturierten Daten, Websites mit strukturierten Daten (erweiterte Website-Indexierung), unstrukturierte Daten mit Metadaten oder Mediendaten
Filtersteuerung Entfernt Einträge aus den zurückgegebenen Ergebnissen Suchanwendungen mit Datenspeichern, die ein Schema unterstützen, z. B. Datenspeicher mit strukturierten Daten, Websites (erweiterte Websiteindexierung und grundlegende Websitesuche), unstrukturierte Daten mit Metadaten oder Mediendaten
Synonymsteuerung Verknüpft Abfragen miteinander Suchanwendungen mit Website (erweiterte Websiteindexierung), strukturierten, unstrukturierten oder Mediendatenspeichern
Weiterleitungssteuerung Weiterleitung zu einem bestimmten URI Alle Such-Apps
Kontrolle fördern Bewirbt einen bestimmten Link für eine Suchanfrage Nur Apps für die grundlegende Websitesuche

Bedingungen

Beim Erstellen eines Steuerelements können Sie optional eine Bedingung definieren, die festlegt, wann das Steuerelement angewendet wird. Bedingungen werden mithilfe von Bedingungsfeldern definiert. Folgende Bedingungsfelder sind verfügbar:

  • queryTerms: Optionales Steuerelement, das angewendet wird, wenn nach bestimmten Suchanfragen gesucht wird. Wenn die Bedingung queryTerms verwendet wird, wird das Steuerelement 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 eine einzelne Control.condition können bis zu zehn verschiedene queryTerms angegeben werden. Wenn keine Suchbegriffe angegeben werden, wird das Feld queryTerms ignoriert.

    Für die Auslieferung von Anzeigen mit Angeboten gelten die folgenden zusätzlichen Einschränkungen:

    • Die Bedingung queryTerms kann nicht angegeben werden, wenn die Bedingung queryRegex festgelegt ist.
    • Für „fullMatch“ muss „true“ festgelegt werden.

  • activeTimeRange: Optionale Einstellung, die angewendet wird, wenn eine Anfrage innerhalb eines bestimmten Zeitraums erfolgt. Es wird geprüft, ob der Zeitpunkt, zu dem eine Anfrage eingegangen ist, zwischen activeTimeRange.startTime und activeTimeRange.endTime liegt. Für eine einzelne Control.condition können bis zu zehn activeTimeRange-Bereiche angegeben werden. Wenn das Feld activeTimeRange nicht angegeben ist, wird es ignoriert.

  • queryRegex: Nur für die Bereitstellungssteuerung „Angebote bewerben“ verfügbar. Optionale Bedingung, die die Steuerung anwendet, wenn die Suchanfrage mit dem angegebenen regulären Ausdruck übereinstimmt. Diese Bedingung kann nicht angegeben werden, wenn Sie die Bedingung queryTerms angeben.

Wenn für eine Steuerung mehrere Bedingungen angegeben sind, wird die Steuerung auf die Suchanfrage angewendet, wenn beide Bedingungstypen erfüllt sind. Wenn für dieselbe Bedingung mehrere Werte angegeben werden, 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 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.

Steuerelemente für die optimierte Auslieferung erstellen und anhängen

Eine Einstellung für die optimierte Auslieferung ist eine Einstellung mit einer boostAction.

So erstellen Sie eine Einstellung für die optimierte Auslieferung:

Weitere Informationen 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 bereits eine App-ID haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und sehen Sie sich die ID der App in der Spalte ID an.

  2. Führen Sie die folgenden curl-Befehle aus, um die Steuerelemente 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 Vertex AI Search-Anwendung.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, darunter Buchstaben, Ziffern, Bindestriche und Unterstriche.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Steuerelements. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden soll. 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 festlegt, wann die Steuerung angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der Abfragewert, mit dem verglichen werden soll. Es ist ein UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, kann 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 „true“ festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn false festgelegt ist, muss SearchRequest.query queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im UTC-Format „Zulu“ gemäß RFC 3339, der den Beginn eines Zeitraums angibt.
      • END_TIMESTAMP: ein Zeitstempel im Format „Zulu“ (UTC) gemäß RFC 3339, der das Ende eines Zeitraums angibt.
    • BOOST_VALUE: eine Gleitkommazahl im Bereich [−1,1]. Wenn der Wert negativ ist, werden die Ergebnisse herabgestuft und erscheinen weiter unten in den Ergebnissen. Wenn der Wert positiv ist, werden die Ergebnisse hervorgehoben (sie werden weiter oben in den Ergebnissen angezeigt). 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 der Boost 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 Dokumentenfeld title kann nicht gefiltert werden.
    • DATA_STORE_RESOURCE_PATH: Der vollständige Ressourcenpfad des Datenspeichers, dessen Dokumente durch diese Einstellung beschleunigt werden sollen. Das Format des vollständigen Ressourcenpfads ist projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Dieser Datenspeicher muss mit der in der Anfrage angegebenen Engine verknüpft sein.

  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.

Steuerelemente für die Filterbereitstellung erstellen und anhängen

Ein Steuerelement für die Filterauslieferung ist ein Steuerelement mit einer filterAction.

Folgen Sie der folgenden Anleitung, um eine Filterbereitstellungssteuerung zu erstellen.

Weitere Informationen 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 bereits eine App-ID haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und sehen Sie sich die ID der App in der Spalte ID an.

  2. Führen Sie die folgenden curl-Befehle aus, um die Steuerelemente 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 Vertex AI Search-Anwendung.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, darunter Buchstaben, Ziffern, Bindestriche und Unterstriche.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Steuerelements. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden soll. 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 festlegt, wann die Steuerung angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der Abfragewert, mit dem verglichen werden soll. Es ist ein UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, kann 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 „true“ festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn false festgelegt ist, muss SearchRequest.query queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im UTC-Format „Zulu“ gemäß RFC 3339, der den Beginn eines Zeitraums angibt.
      • END_TIMESTAMP: ein Zeitstempel im Format „Zulu“ (UTC) gemäß RFC 3339, der das Ende eines Zeitraums angibt.
    • FILTER: Ein String, der die Anforderungen angibt, die das Dokument erfüllen muss. Wenn das Dokument allen Anforderungen entspricht, 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 Dokumentenfeld 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.

Steuerelemente für die Bereitstellung von Synonyme erstellen und anhängen

Eine Synonymbereitstellungssteuerung ist ein Steuerelement mit einem synonymsAction.

Folgen Sie der Anleitung unten, um eine Einstellung für die Auslieferung von Synonyme zu erstellen.

Weitere Informationen 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 bereits eine App-ID haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und sehen Sie sich die ID der App in der Spalte ID an.

  2. Führen Sie die folgenden curl-Befehle aus, um die Steuerelemente 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 Vertex AI Search-Anwendung.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, darunter Buchstaben, Ziffern, Bindestriche und Unterstriche.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Steuerelements. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden soll. 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 festlegt, wann die Steuerung angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der Abfragewert, mit dem verglichen werden soll. Es ist ein UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, kann 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 „true“ festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn false festgelegt ist, muss SearchRequest.query queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im UTC-Format „Zulu“ gemäß RFC 3339, der den Beginn eines Zeitraums angibt.
      • END_TIMESTAMP: ein Zeitstempel im Format „Zulu“ (UTC) gemäß RFC 3339, der das Ende eines Zeitraums angibt.
    • SYNONYMS_N: Eine Liste von Strings, die miteinander verknüpft sind, sodass für jeden String mit höherer Wahrscheinlichkeit ähnliche Ergebnisse angezeigt werden. Die Wahrscheinlichkeit, dass Sie ähnliche Ergebnisse erhalten, ist zwar höher, 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 Synonyme angeben. Maximal sind 100 Synonyme möglich. Jedes Synonym muss UTF-8-codiert und in Kleinbuchstaben geschrieben sein. Strings dürfen nicht doppelt vorhanden sein. 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 einer Weiterleitungssteuerung können Nutzer zu einem angegebenen URI weitergeleitet werden. Weiterleitungssteuerungen sind als Steuerelement mit einem redirectAction definiert.

So erstellen Sie eine Weiterleitungsbereitstellungssteuerung:

Weitere Informationen 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 bereits eine App-ID haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und sehen Sie sich die ID der App in der Spalte ID an.

  2. Führen Sie die folgenden curl-Befehle aus, um die Steuerelemente 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 Vertex AI Search-Anwendung.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, darunter Buchstaben, Ziffern, Bindestriche und Unterstriche.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Steuerelements. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden soll. 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 festlegt, wann die Steuerung angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der Abfragewert, mit dem verglichen werden soll. Es ist ein UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000]. Wenn FULL_MATCH_1 true ist, kann 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 „true“ festgelegt ist, muss SearchRequest.query vollständig mit queryTerm.value übereinstimmen. Wenn false festgelegt ist, muss SearchRequest.query queryTerm.value als Teilstring enthalten.
      • START_TIMESTAMP: ein Zeitstempel im UTC-Format „Zulu“ gemäß RFC 3339, der den Beginn eines Zeitraums angibt.
      • END_TIMESTAMP: ein Zeitstempel im Format „Zulu“ (UTC) gemäß RFC 3339, der das Ende eines Zeitraums 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 auf Ihre Seite für den technischen Support einrichten, anstatt Suchergebnisse für „Support“ zurückzugeben (oder nicht zurückzugeben). In diesem Beispiel wird der Weiterleitungs-URI zu "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.

Steuerelemente für die Auslieferung von Anzeigen erstellen und anhängen

Mit einem Steuerelement für die Anzeigenbereitstellung können Sie einen Link als gesponsertes Ergebnis präsentieren. Diese Einstellung ist nur für Website-Datenspeicher mit grundlegender Websitesuche verfügbar.

Im Gegensatz zu anderen Bereitstellungssteuerungen müssen Sie die Werbesteuerung nicht an die Bereitstellungskonfiguration der App anhängen. Wenn Sie eine Werbesteuerung für eine App erstellen und aktivieren, wird sie aktiviert. Im Gegensatz zu anderen Einstellungen für die Anzeigenbereitstellung können Sie die Einstellung für Angebote aktivieren oder deaktivieren.

Steuerelemente für Werbung werden mit einer promoteAction definiert.

Damit ein Steuerelement für Werbung erstellt werden kann, ist in der Erstellungsanfrage eines der folgenden Felder erforderlich:

  • Das Feld queryTerms, bei dem fullMatch auf true gesetzt ist
  • Das Feld queryRegex

So erstellen Sie eine Einstellung für die Auslieferung von Anzeigen mit Anzeigenaufforderungen:

Weitere Informationen 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 bereits eine App-ID haben, fahren Sie mit dem nächsten Schritt fort.

    1. Rufen Sie in der Google Cloud Console die Seite Agent Builder auf.

      Zu Apps wechseln

    2. Suchen Sie auf der Seite Apps nach dem Namen Ihrer App und sehen Sie sich die ID der App in der Spalte ID an.

  2. Führen Sie die folgenden curl-Befehle aus, um die Steuerelemente 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": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "title": "URI_TITLE",
     "uri": "URI",
     "description": "URI_DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Die Nummer oder ID Ihres Google Cloud -Projekts.
    • APP_ID: die ID der Vertex AI Search-Anwendung.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, darunter Buchstaben, Ziffern, Bindestriche und Unterstriche.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Steuerelements. Google empfiehlt, dass dieser Name angibt, wann oder warum das Steuerelement verwendet werden soll. 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: Optionales Objekt, das festlegt, wann das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • queryTerms: Kann nicht mit dem Feld queryRegex verwendet werden.
        • VALUE: Der Abfragewert, mit dem verglichen werden soll. Es ist ein UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000].
      • activeTimeRange:
        • START_TIMESTAMP: ein Zeitstempel im UTC-Format „Zulu“ gemäß RFC 3339, der den Beginn eines Zeitraums angibt.
        • END_TIMESTAMP: ein Zeitstempel im Format „Zulu“ (UTC) gemäß RFC 3339, der das Ende eines Zeitraums angibt.
      • queryRegex: Kann nicht mit dem Feld queryTerms verwendet werden.
        • VALUE_REGEX: Ein regulärer Ausdruck, mit dem die Abfrage abgeglichen werden soll. Diese Option ist nur für die Einstellung „Angebote präsentieren“ verfügbar.
    • DATA_STORE_RESOURCE_PATH: Der vollständige Ressourcenpfad des Datenspeichers, dessen Suchergebnisse die beworbene URL enthalten. Das Format des vollständigen Ressourcenpfads ist projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Dieser Datenspeicher muss mit der in der Anfrage angegebenen Engine verknüpft sein.
    • URI_TITLE: Ein Pflichtfeld, in dem der Titel des URI angegeben wird, der im Suchergebnis angezeigt wird.
    • URI: Ein Pflichtfeld, in dem der URI-Link angegeben wird, zu dem das Suchergebnis den Nutzer weiterleitet. Dieser URI muss nicht im Datenspeicher enthalten sein.
    • URI_DESCRIPTION: Optionales Feld zur Beschreibung des URI, der im Suchergebnis angezeigt wird.
    • ENABLED_TRUE|FALSE: Ein optionales boolesches Feld, das angibt, ob die Einstellung „Angebote präsentieren“ aktiviert und an die App angehängt ist. Wenn Sie dieses Feld auf false setzen, wird die Einstellung „Angebote präsentieren“ deaktiviert. Damit sie wirksam wird, müssen Sie sie aktualisieren, indem Sie sie aktivieren, wie im nächsten Schritt erläutert. Weitere Informationen finden Sie unter promoteAction.

  3. Optional: Wenn Sie ein Steuerelement für Werbung nach dem Erstellen aktivieren oder deaktivieren möchten, rufen Sie die Methode engines.control.patch auf.

    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/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

Beispiel

Wenn Sie eine Suchanfrage an die App senden, die mit der für das Steuerelement „Angebot“ angegebenen Suchanfrage oder dem regulären Ausdruck für Suchanfragen übereinstimmt, wird der entsprechende Link in der Antwort angezeigt.

Angenommen, Sie erstellen ein Promote-Element mit der folgenden Konfiguration:

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

Senden Sie dann die folgende Suchanfrage:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Sie sollten eine JSON-Antwort ähnlich wie die folgende gekürzte Antwort erhalten. Die Antwort enthält das Feld searchLinkPromotions mit dem beworbenen Link.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Nächste Schritte

  • Um die Auswirkungen einer Auslieferungssteuerung auf die Suchqualität einer generischen Such-App zu verstehen, sollten Sie die Suchqualität bewerten. Weitere Informationen finden Sie unter Suchqualität bewerten.