Bereitstellungseinstellungen konfigurieren

Mit Bereitstellungseinstellungen (auch als Steuerelemente bezeichnet) wird das Standardverhalten bei der Bereitstellung einer Anfrage geändert, wenn Ergebnisse zurückgegeben werden. Bereitstellungseinstellungen wirken sich auf Datenspeicherebene aus.

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.

Bereitstellungseinstellungen

Wenn Sie die Ergebnisse einer Anfrage ändern möchten, müssen Sie zuerst eine Bereitstellungseinstellung erstellen. Hängen Sie diese Bereitstellungseinstellung dann an die Bereitstellungskonfiguration einer App an. In einer Bereitstellungskonfiguration werden Metadaten konfiguriert, 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.

Einige Steuerelemente, z. B. die Boost-Steuerung, sind von Datenspeichern abhängig. Wenn ein Datenspeicher aus einer App entfernt wird, werden alle datenspeicherabhängigen Einstellungen ebenfalls aus dieser App entfernt und deaktiviert, aber nicht gelöscht.

Arten von Bereitstellungseinstellungen

Die folgenden Arten von Bereitstellungseinstellungen 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
Synonymsteuerung Verknüpft Abfragen miteinander Suchanwendungen mit strukturierten oder unstrukturierten Datenspeichern
Weiterleitungssteuerung Leitet zu einem angegebenen URI weiter Alle Suchanwendungen
Promote-Steuerung Hebt einen bestimmten Link für eine Anfrage als bevorzugtes Suchergebnis hervor 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 über Bedingungsfelder definiert. Folgende Bedingungsfelder sind verfügbar:

  • queryTerms: Ein optionales Steuerelement, das angewendet wird, wenn nach bestimmten Anfragen 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 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: Ein optionales Steuerelement, das angewendet wird, wenn eine Anfrage innerhalb eines bestimmten Zeitraums erfolgt. Es 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 ein Steuerelement mehrere Bedingungen angegeben sind, wird das Steuerelement auf die Suchanfrage angewendet, wenn alle Bedingungen erfüllt sind. Wenn mehrere Werte für dieselbe Bedingung angegeben sind, muss nur einer der Werte zutreffen, 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 das Steuerelement immer angewendet.

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

Boost-Bereitstellungseinstellungen erstellen und anhängen

Eine Boost-Bereitstellungseinstellung ist ein Steuerelement mit einer boostAction.

So erstellen Sie eine Boost-Bereitstellungseinstellung:

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

  1. App-ID suchen. 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.

      Gehen Sie zu Apps

    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 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 App.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der menschenlesbare Name des Steuerelements. Google empfiehlt, dass dieser Name darauf hinweist, 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 das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, mit dem abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit einer Länge von [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld höchstens 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 eingestuft. 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 Hochstufung angewendet. Andernfalls ändert sich nichts. Wenn dieses Feld leer ist, wird die Hochstufung 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 dieses Steuerelement hochgestuft 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 das Steuerelement 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 IDs der Steuerelemente, die Sie im vorherigen Schritt erstellt haben.

Filter-Bereitstellungseinstellungen erstellen und anhängen

Eine Filter-Bereitstellungseinstellung ist ein Steuerelement mit einer filterAction.

So erstellen Sie eine Filter-Bereitstellungseinstellung:

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

  1. App-ID suchen. 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.

      Gehen Sie zu Apps

    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 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 App.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der menschenlesbare Name des Steuerelements. Google empfiehlt, dass dieser Name darauf hinweist, 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 das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, mit dem abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit einer Länge von [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld höchstens 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 das Steuerelement 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 IDs der Steuerelemente, die Sie im vorherigen Schritt erstellt haben.

Synonym-Bereitstellungseinstellungen erstellen und anhängen

Eine Synonym-Bereitstellungseinstellung ist ein Steuerelement mit einer synonymsAction.

So erstellen Sie eine Synonym-Bereitstellungseinstellung:

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

  1. App-ID suchen. 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.

      Gehen Sie zu Apps

    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 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 App.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der menschenlesbare Name des Steuerelements. Google empfiehlt, dass dieser Name darauf hinweist, 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 das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, mit dem abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit einer Länge von [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld höchstens 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, wodurch es wahrscheinlicher ist, dass für jeden String ähnliche Ergebnisse angezeigt werden. Obwohl es wahrscheinlicher ist, dass Sie ähnliche Ergebnisse erhalten, wenn Sie nach jedem der synonymen Einträ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 das Steuerelement 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 IDs der Steuerelemente, die Sie im vorherigen Schritt erstellt haben.

Bereitstellungseinstellungen für Weiterleitungen erstellen und anhängen

Mit einer Bereitstellungseinstellung für Weiterleitungen können Nutzer zu einem angegebenen URI weitergeleitet werden. Bereitstellungseinstellungen für Weiterleitungen werden als Steuerelemente mit einer redirectAction definiert.

So erstellen Sie eine Bereitstellungseinstellung für Weiterleitungen:

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

  1. App-ID suchen. 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.

      Gehen Sie zu Apps

    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 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 App.
    • CONTROL_ID: Eine eindeutige Kennung für das Steuerelement. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der menschenlesbare Name des Steuerelements. Google empfiehlt, dass dieser Name darauf hinweist, 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 das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • VALUE: Der spezifische Abfragewert, mit dem abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit einer Länge von [1, 5000]. Wenn FULL_MATCH_1 true ist, darf dieses Feld höchstens 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 den 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 das Steuerelement 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 IDs der Steuerelemente, die Sie im vorherigen Schritt erstellt haben.

Promote-Bereitstellungseinstellungen erstellen und anhängen

Mit einer Promote-Bereitstellungseinstellung können Sie einen Link als bevorzugtes Suchergebnis anzeigen lassen. Diese Option 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 diese an die Bereitstellungskonfiguration der App anhängen.

Promote-Steuerelemente werden mit einer 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 eine Promote-Bereitstellungseinstellung:

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

  1. App-ID suchen. 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.

      Gehen Sie zu Apps

    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 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_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 das Steuerelement. Die ID kann [1–63] Zeichen enthalten, die Buchstaben, Ziffern, Bindestriche und Unterstriche sein können.
    • DISPLAY_NAME: Der menschenlesbare Name des Steuerelements. Google empfiehlt, dass dieser Name darauf hinweist, 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 das Steuerelement angewendet werden soll. Enthält die folgenden Felder:
      • queryTerms:
        • VALUE: Der spezifische Abfragewert, mit dem abgeglichen werden soll. Es handelt sich um einen UTF-8-String in Kleinbuchstaben mit einer Länge von [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 URL als bevorzugtes Suchergebnis 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, in dem der Ressourcenpfad des Dokuments angegeben wird, das als bevorzugtes Suchergebnis angezeigt 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 Dokuments oder der Webseite angeben, der als bevorzugtes Suchergebnis angezeigt werden soll. 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 Promote-Steuerelemente, die Sie benötigen, um das Promote-Steuerelement an Ihre Suchanwendung anzuhängen.

  3. Hängen Sie das Steuerelement 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 bevorzugten 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 IDs der Steuerelemente, die Sie im vorherigen Schritt erhalten haben.

Nächste Schritte

  • Um die Auswirkungen einer Bereitstellungseinstellung auf die Suchqualität einer App zu verstehen, müssen Sie die Suchqualität bewerten.