Esta página foi traduzida pela API Cloud Translation.

Configurar controles de exibição

Os controles de exibição (também chamados de controles) mudam o comportamento padrão de como uma solicitação é atendida quando os resultados são retornados. Os controles de exibição atuam no nível do repositório de dados.

Por exemplo, os controles podem impulsionar e ocultar resultados, filtrar entradas dos resultados retornados, associar strings entre si como sinônimos ou redirecionar resultados para URIs especificados.

Sobre os controles de veiculação

Para mudar os resultados de uma solicitação, primeiro crie um controle de exibição. Em seguida, anexe esse controle à configuração de exibição de um app. Uma configuração de exibição configura metadados usados para gerar resultados no momento da exibição, como resultados da pesquisa ou respostas. Um controle de veiculação só afeta as solicitações veiculadas pelo app se estiver anexado à configuração de veiculação dele.

Alguns controles, como os de reforço, têm dependências de repositórios de dados. Se um repositório de dados for removido de um app, todos os controles dependentes dele também serão removidos e ficarão inativos, mas não serão excluídos.

Tipos de controle de veiculação

Os seguintes tipos de controles de exibição estão disponíveis:

Controle	Descrição	Disponível para
Controle de boost	Muda a ordem dos resultados retornados	Pesquisar apps com repositórios de dados que oferecem suporte a um esquema, como repositórios que contêm dados estruturados ou não estruturados com metadados
Controle de filtros	Remove entradas dos resultados retornados.	Pesquisar apps com repositórios de dados que oferecem suporte a um esquema, como repositórios que contêm dados estruturados ou não estruturados com metadados
Controle de sinônimos	Associa consultas entre si	Apps de pesquisa com repositórios de dados estruturados ou não estruturados
Controle de redirecionamento	Redireciona para um URI especificado.	Todos os apps de pesquisa
Promover controle	Promove um link especificado para uma consulta.	Apps de pesquisa com repositórios de dados estruturados ou não estruturados

Sobre as condições

Ao criar um controle, você pode definir uma condição que determina quando ele será aplicado. As condições são definidas usando campos de condição. Os seguintes campos de condição estão disponíveis:

queryTerms. Um controle opcional que é aplicado quando consultas específicas são pesquisadas. Quando a condição queryTerms é usada, o controle é aplicado quando o valor de queryTerms corresponde a um termo em SearchRequest.query. Os termos de consulta só podem ser usados quando o Control.searchUseCase é definido como SOLUTION_TYPE_SEARCH. É possível especificar até 10 queryTerms diferentes em um único Control.condition. Se nenhum termo de consulta for especificado, o campo queryTerms será ignorado.

Para criar um controle de promoção, especifique o campo queryTerms com fullMatch definido como true ou false.
activeTimeRange. Um controle opcional que é aplicado quando uma solicitação ocorre em um intervalo de tempo especificado. Ele verifica se o horário em que uma solicitação foi recebida está entre activeTimeRange.startTime e activeTimeRange.endTime. É possível especificar até 10 intervalos de activeTimeRange em um único Control.condition. Se o campo activeTimeRange não for especificado, ele será ignorado.

Se várias condições forem especificadas para um controle, ele será aplicado à solicitação de pesquisa quando os dois tipos de condição forem atendidos. Se vários valores forem especificados para a mesma condição, apenas um deles precisará corresponder para que a condição seja atendida.

Por exemplo, considere a seguinte condição com dois termos de consulta especificados:

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

A condição será atendida para uma solicitação com SearchRequest.query="gShoe" ou SearchRequest.query="gBoot", mas não com SearchRequest.query="gSandal" ou qualquer outra string.

Se nenhuma condição for especificada, o controle será sempre aplicado.

Para mais informações, consulte o campo Condition na referência da API.

Criar e anexar controles de veiculação de reforço

Um controle de veiculação de aumento é definido como um controle com um boostAction.

Use as instruções a seguir para criar um controle de veiculação de reforço.

Para detalhes dos campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Execute os comandos curl a seguir para criar seus controles.
```
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"
 }
}'
```
Substitua:
- PROJECT_ID: o número ou ID do seu projeto do Google Cloud
- APP_ID: o ID do app.
- CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
- DISPLAY_NAME: o nome legível do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com tamanho [1,128].
- USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
- CONDITION: um campo opcional que define quando o controle deve ser aplicado. Contém os seguintes campos:
  - VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000]. Se FULL_MATCH_1 for true, esse campo poderá ter no máximo três termos separados por espaços.
  - FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
  - START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
  - END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
- BOOST_VALUE: um número de ponto flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são rebaixados (aparecem mais abaixo nos resultados). Quando o valor é positivo, os resultados são promovidos (aparecem mais acima nos resultados). Para mais informações, consulte boostAction.
- FILTER: uma string que especifica os requisitos que o documento precisa cumprir. Se o documento atender a todos os requisitos, o aumento será aplicado. Caso contrário, não haverá mudanças. Se este campo estiver vazio, o reforço será aplicado a todos os documentos no repositório de dados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro. Observação: não é possível filtrar o campo de documento title.
- DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do repositório de dados cujos documentos devem ser promovidos por esse controle. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esse repositório de dados precisa estar anexado ao mecanismo especificado na solicitação.

Anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch.

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"]
}'

Substitua BOOST_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de filtros

Um controle de serviço de filtro é definido como um controle com um filterAction.

Use as instruções a seguir para criar um controle de exibição de filtro.

Para detalhes dos campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Execute os comandos curl a seguir para criar seus controles.
```
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"
 }
}'
```
Substitua:
- PROJECT_ID: o número ou ID do seu projeto do Google Cloud
- APP_ID: o ID do app.
- CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
- DISPLAY_NAME: o nome legível do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com tamanho [1,128].
- USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
- CONDITION: um campo opcional que define quando o controle deve ser aplicado. Contém os seguintes campos:
  - VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000]. Se FULL_MATCH_1 for true, esse campo poderá ter no máximo três termos separados por espaços.
  - FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
  - START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
  - END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
- FILTER: uma string que especifica os requisitos que o documento precisa cumprir. Se o documento atender a todos os requisitos, ele será retornado nos resultados. Caso contrário, o documento não vai aparecer nos resultados. Para a sintaxe de filtragem, consulte Sintaxe da expressão de filtro. Veja mais informações em filterAction. Observação: não é possível filtrar o campo de documento title.

Anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch.

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"]
}'

Substitua FILTER_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de sinônimos

Um controle de exibição de sinônimos é definido como um controle com um synonymsAction.

Use as instruções a seguir para criar um controle de exibição de sinônimos.

Para detalhes dos campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Execute os comandos curl a seguir para criar seus controles.
```
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"]
 }
}'
```
Substitua:
- PROJECT_ID: o número ou ID do seu projeto do Google Cloud
- APP_ID: o ID do app.
- CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
- DISPLAY_NAME: o nome legível do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com tamanho [1,128].
- USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
- CONDITION: um campo opcional que define quando o controle deve ser aplicado. Contém os seguintes campos:
  - VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000]. Se FULL_MATCH_1 for true, esse campo poderá ter no máximo três termos separados por espaços.
  - FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
  - START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
  - END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
- SYNONYMS_N: uma lista de strings associadas entre si, o que aumenta a probabilidade de cada uma mostrar resultados semelhantes. Embora seja mais provável que você receba resultados semelhantes, ao pesquisar cada uma das entradas de sinônimos, talvez não receba todos os resultados relevantes para todos os sinônimos associados. É preciso especificar pelo menos dois sinônimos, sendo possível especificar até 100. Cada sinônimo precisa ser codificado em UTF-8 e estar em letras minúsculas. Não são permitidas strings duplicadas. Por exemplo, você pode adicionar "pixel", "smartphone android" e "smartphone do google" como sinônimos. Para ver mais informações, consulte synonymsAction.

Anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch.

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"]
}'

Substitua SYNONYMS_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de redirecionamento

Um controle de veiculação de redirecionamento permite redirecionar os usuários para um URI fornecido. Os controles de redirecionamento são definidos como um controle com um redirectAction.

Use as instruções a seguir para criar um controle de veiculação de redirecionamento.

Para detalhes dos campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Execute os comandos curl a seguir para criar seus controles.
```
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"
 }
}'
```
Substitua:
- PROJECT_ID: o número ou ID do seu projeto do Google Cloud
- APP_ID: o ID do app.
- CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
- DISPLAY_NAME: o nome legível do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com tamanho [1,128].
- USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
- CONDITION: um campo opcional que define quando o controle deve ser aplicado. Contém os seguintes campos:
  - VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000]. Se FULL_MATCH_1 for true, esse campo poderá ter no máximo três termos separados por espaços.
  - FULL_MATCH: um booleano que indica se a consulta de pesquisa precisa corresponder exatamente ao termo de consulta. Quando definido como true, exige que SearchRequest.query corresponda completamente ao queryTerm.value. Quando definido como false, exige que SearchRequest.query contenha queryTerm.value como uma substring.
  - START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
  - END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
- REDIRECT_URI_N: um URI para onde você é redirecionado. Pode ter um comprimento máximo de 2.000 caracteres. Por exemplo, se o valor do termo de consulta for "suporte", você poderá definir um redirecionamento para a página de suporte técnico em vez de retornar (ou não retornar) resultados da pesquisa para "suporte". Neste exemplo, o URI de redirecionamento se torna "https://www.example.com/support". Veja mais informações em redirectAction.

Anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch.

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"]
}'

Substitua REDIRECT_ID_N pelos IDs de controle que você criou na etapa anterior.

Criar e anexar controles de veiculação de promoção

Um controle de exibição de promoção permite mostrar um link como um resultado promovido. Esse controle está disponível para apps de pesquisa com repositórios de dados estruturados ou não estruturados e apps de pesquisa combinada.

Para que o controle de promoção entre em vigor, é necessário anexá-lo à configuração de veiculação do app.

Os controles de promoção são definidos usando um promoteAction.

Para criar um controle de promoção, especifique o campo queryTerms com fullMatch definido como true ou false.

Use as instruções a seguir para criar um controle de veiculação de promoção.

Para detalhes dos campos, consulte a referência da API engines.controls e a referência da API engines.controls.create.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Execute os comandos curl a seguir para criar seus controles.
```
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",
  }
 }
}'
```
Substitua:
- PROJECT_ID: o número ou ID do seu projeto do Google Cloud
- APP_ID: o ID do app.
- CONTROL_ID: um identificador exclusivo para o controle. O ID pode conter de 1 a 63 caracteres, que podem ser letras, dígitos, hifens e sublinhados.
- DISPLAY_NAME: o nome legível do controle. O Google recomenda que esse nome indique quando ou por que usar o controle. Precisa ser uma string codificada em UTF-8 com tamanho [1,128].
- USE_CASE: precisa ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, Condition.queryTerms não poderá ser usado na condição.
- Condition: um objeto opcional que define quando o controle deve ser aplicado. Contém os seguintes campos:
  - queryTerms:
    - VALUE: o valor de consulta específico a ser correspondido. É uma string UTF-8 em letras minúsculas com comprimento [1, 5000].
    - FULL_MATCH_TRUE|FALSE: um booleano para indicar se o termo de consulta precisa ser totalmente correspondido.
  - activeTimeRange:
    - START_TIMESTAMP: um carimbo de data/hora no formato RFC 3339 UTC "Zulu" para indicar o início de um período.
    - END_TIMESTAMP: um carimbo de data/hora no formato UTC RFC 3339 "Zulu" para indicar o fim de um período.
- DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do repositório de dados cujos resultados da pesquisa contêm o URL promovido. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Esse repositório de dados precisa estar anexado ao mecanismo especificado na solicitação.
- DOCUMENT_RESOURCE_PATH: um campo para especificar o caminho do recurso do documento a ser promovido. Você precisa fornecer o ID do documento no campo DOCUMENT_RESOURCE_PATH, o URI no campo URI ou ambos.
  
  O formato do caminho completo do recurso é: projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
- TITLE: um campo obrigatório para especificar o título do documento ou da página da Web a ser promovida. Esse título é exibido no resultado da pesquisa.
- URI: um campo para especificar o URI em que o resultado da pesquisa leva o usuário. Você precisa fornecer o ID do documento no campo DOCUMENT_RESOURCE_PATH, o URI no campo URI ou ambos.
- URI_DESCRIPTION: um campo opcional para descrever o URI, que é exibido no resultado da pesquisa.
Resposta

Você receberá uma resposta JSON semelhante a esta:
```
{
 "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
  }
 }
}
```
A resposta contém IDs de controle de promoção que você precisa anexar ao controle de promoção no seu app de pesquisa.

Anexe o controle à configuração de exibição do app usando o método engines.servingConfigs.patch. A ordem em que você anexa o promoteControlIds na solicitação a seguir é a ordem em que os resultados promovidos são retornados.

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"]
}'

Substitua PROMOTE_ID_N pelos IDs de controle que você recebeu na etapa anterior.

A seguir

Para entender o impacto de um controle de veiculação na qualidade da pesquisa de um app, avalie a qualidade da pesquisa.

Configurar controles de exibição

Sobre os controles de veiculação

Tipos de controle de veiculação

Sobre as condições

Criar e anexar controles de veiculação de reforço

Criar e anexar controles de veiculação de filtros

Criar e anexar controles de veiculação de sinônimos

Criar e anexar controles de veiculação de redirecionamento

Criar e anexar controles de veiculação de promoção

Resposta

A seguir