Bereitstellungssteuerung für die Suche 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 Bereitstellungssteuerung 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 an bestimmte URIs weiterleiten.

Auf dieser Seite werden Bereitstellungseinstellungen für Such-Apps beschrieben. Informationen zur Verwendung von Bereitstellungssteuerungen mit Media-Empfehlungen finden Sie unter Bereitstellungskonfigurationen für Media erstellen und verwalten.

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 Suchanwendung an. 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 bereitgestellt werden, wenn die Einstellung an die Bereitstellungskonfiguration der App angehängt ist.

Einige Steuerelemente, z. B. Steuerelemente für Kampagnen mit automatischen Geboten, sind von Datenspeichern abhängig. Wenn ein Datenspeicher aus einer App entfernt wird, werden alle datenspeicherabhängigen Steuerelemente ebenfalls aus dieser App entfernt und inaktiviert, aber nicht gelöscht.

Typen von Bereitstellungseinstellungen

Folgende Bereitstellungssteuerungen sind verfügbar:

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:

• Suchbegriffe (queryTerms): Eine optionale Steuerung, die 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 ein einzelnes Control.condition können bis zu 10 verschiedene queryTerms angegeben werden. Wenn keine Suchbegriffe angegeben sind, wird das Feld queryTerms ignoriert.

  Für eine Kontrollgruppe für die Anzeigenauslieferung kann queryTerms nicht angegeben werden, wenn Sie die Bedingung queryRegex angeben. Diese ist nur für die einfache Websitesuche anwendbar. Außerdem muss das Feld fullMatch für die einfache Websitesuche auf true gesetzt werden, wenn queryTerms angegeben ist. Bei allen anderen Such-Apps wird nur queryTerms unterstützt und fullMatch kann auf true oder false festgelegt werden.

• Zeitraum (activeTimeRange): Ein optionales Steuerelement, das 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.

• queryRegex: Nur für eine Bereitstellungssteuerung für die Bewerbung für die einfache Website-Suche verfügbar. Dies ist eine optionale Bedingung, mit der die Steuerung angewendet wird, wenn die Anfrage dem angegebenen regulären Ausdruck entspricht. 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 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

Mit einem Boost-Bereitstellungssteuerelement werden die Ergebnisse neu angeordnet, indem sie basierend auf den angewendeten Bedingungen höher oder niedriger eingestuft werden. Beim Boost wird ein Multiplikationsfaktor auf das Ranking eines Dokuments angewendet, das die Boost-Bedingungen erfüllt.

So erstellen und fügen Sie eine Steuerung für die Steigerung hinzu:

Filterbereitstellungssteuerelemente erstellen und anhängen

Ein Filter-Serving-Kontrollbereich ist ein Kontrollbereich mit einem filterAction.

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 KI-Anwendungen 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 Vertex AI Search-Anwendung.
   • CONTROL_ID: Eine eindeutige ID 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 KI-Anwendungen 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 Vertex AI Search-Anwendung.
   • CONTROL_ID: Eine eindeutige ID 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 Synonyme angeben. Maximal sind 100 Synonyme möglich. 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 KI-Anwendungen 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 Vertex AI Search-Anwendung.
   • CONTROL_ID: Eine eindeutige ID 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 Promote-Bereitstellungssteuerelement können Sie einen Link als beworbenes Ergebnis anzeigen lassen. Es ist für die folgenden Arten von Suchdatenspeichern verfügbar:

• Websitedatenspeicher mit einfacher Websitesuche: Bei diesen Datenspeichern müssen Sie der Serving-Konfiguration der App keine Promote-Kontrollgruppe hinzufügen. Wenn Sie eine Promote-Kontrollgruppe erstellen und aktivieren, wird sie automatisch aktiviert. Sie können ein Promote-Steuerelement aktivieren oder deaktivieren.

• Datenspeicher mit strukturierten und unstrukturierten Daten, Websitedaten mit erweiterter Websiteindexierung und kombinierte Suchanwendungen: Bei diesen Datenspeichern müssen Sie das Promote-Steuerelement an die Serving-Konfiguration anhängen.

Promote-Steuerelemente werden mit einem promoteAction definiert.

Damit ein Promote-Kontrollsegment erstellt werden kann, muss im Erstellungsantrag eines der folgenden Felder angegeben werden:

• queryTerms: Diese Bedingung kann nicht angegeben werden, wenn Sie die Bedingung queryRegex angeben, die nur für die einfache Websuche gilt. Für die einfache Website-Suche muss fullMatch auf true festgelegt werden, wenn queryTerms angegeben ist. Bei allen anderen Such-Apps wird nur queryTerms unterstützt und fullMatch kann auf true oder false festgelegt werden.
• queryRegex: Nur für eine Bereitstellungssteuerung für die Bewerbung für die einfache Website-Suche verfügbar. Mit dieser Bedingung wird die Steuerung angewendet, wenn die Anfrage mit dem angegebenen regulären Ausdruck übereinstimmt. Diese Bedingung kann nicht angegeben werden, wenn Sie die Bedingung queryTerms angeben.

Das heißt, für die einfache Website-Suche müssen Sie entweder das Feld queryTerms mit fullMatch auf true festlegen oder das Feld queryRegex angeben. Geben Sie für alle anderen Suchtypen das Feld queryTerms mit fullMatch auf true oder false an.

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

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 KI-Anwendungen 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": true
       }
     ],
     "activeTimeRange": [
       {
         "startTime": "START_TIMESTAMP",
         "endTime": "END_TIMESTAMP"
       }
     ],
     "queryRegex": "VALUE_REGEX"
   },
   "promoteAction": {
     "dataStore": "DATA_STORE_RESOURCE_PATH",
     "searchLinkPromotion": {
        "document": "DOCUMENT_RESOURCE_PATH",
        "title": "TITLE",
        "uri": "URI",
        "description": "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 ID 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: Es kann nicht mit dem Feld queryRegex verwendet werden.
       • VALUE: Der spezifische Abfragewert, der abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit der Länge [1, 5000].
     • 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.
     • queryRegex: Nur für Datenspeicher mit einfacher Websitesuche verfügbar. Dieses Feld kann nicht mit dem Feld queryTerms verwendet werden.
       • VALUE_REGEX: Ein regulärer Ausdruck, mit dem die Abfrage abgeglichen werden soll.
   • 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 Dokumentressourcenpfads des Dokuments, das beworben werden soll:
     • Für Suchdatenspeicher mit strukturierten und unstrukturierten Daten müssen Sie entweder den Dokumentressourcenpfad 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.
     • Bei Datenspeichern für Websitedaten muss dieses Feld nicht festgelegt werden. Stattdessen muss das URI-Feld festgelegt werden.
   • 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 Pflichtfeld, in dem der URI-Link angegeben wird, zu dem der Nutzer über das Suchergebnis gelangt. Dieser URI muss nicht im Datenspeicher enthalten sein.
     • Für Suchdatenspeicher mit strukturierten und unstrukturierten Daten müssen Sie entweder den Dokumentressourcenpfad im Feld DOCUMENT_RESOURCE_PATH, den URI im Feld URI oder beides angeben.
     • Bei Websitedatenspeichern ist dies ein Pflichtfeld, das Sie festlegen müssen.
   • DESCRIPTION: Ein optionales Feld zur Beschreibung des zu bewerbenden Dokuments oder der zu bewerbenden Webseite, das im Suchergebnis angezeigt wird.
   • ENABLED_TRUE|FALSE: Ein optionales boolesches Feld, das angibt, ob die Promote-Kontrollgruppe aktiviert und mit der App verknüpft ist. Dieses Feld gilt nur für Websitedatenspeicher mit einfacher Websuche. Wenn Sie dieses Feld auf false setzen, wird die Steuerung für die Auslieferung von Werbeaktionen deaktiviert. Damit die Steuerung wirksam wird, müssen Sie sie aktivieren, wie im nächsten Schritt beschrieben. Weitere Informationen finden Sie unter promoteAction.

   Antwort

   Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

3. Hängen Sie für alle Suchanwendungen mit Ausnahme der einfachen Website-Suche das Steuerelement mit der Methode engines.servingConfigs.patch an die Bereitstellungskonfiguration der App an. Die Reihenfolge, in der die promoteControlIds in der folgenden Anfrage angehängt werden, entspricht der 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 erstellt haben.

4. Optional: Für die einfache Websuche müssen Sie das Steuerelement nicht an die Bereitstellungskonfiguration der App anhängen. Bei der einfachen Website-Suche können Sie ein Promote-Steuerelement jedoch nach der Erstellung aktivieren oder deaktivieren, indem Sie die Methode engines.control.patch aufrufen.

   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 mit einer Abfrage an die App senden, die der für die Promote-Kontrollgruppe angegebenen Abfrage oder dem regulären Ausdruck für die Abfrage entspricht, wird der beworbene Link in der Antwort angezeigt.

Angenommen, Sie erstellen eine Kontrollgruppe für die Steigerung mit der folgenden Konfiguration in einem Datenspeicher mit einfacher Website-Suche:

{
 "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
  }
 }
}

Anschließend senden Sie die folgende search-Anfrage:

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 der folgenden gekürzten 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 Serving-Kontrollgruppe auf die Suchqualität einer benutzerdefinierten Such-App zu verstehen, müssen Sie die Suchqualität bewerten. Weitere Informationen finden Sie unter Suchqualität bewerten.