Configure os controlos de publicação

Os controlos de publicação (também denominados controlos) alteram o comportamento predefinido de como um pedido é publicado quando são devolvidos resultados. Os controlos de publicação atuam ao nível do armazenamento de dados.

Por exemplo, os controlos podem aumentar e ocultar resultados, filtrar entradas dos resultados devolvidos, associar strings entre si como sinónimos ou redirecionar resultados para URIs especificados.

Acerca dos controlos de publicação

Para alterar os resultados de um pedido, crie primeiro um controlo de publicação. Em seguida, associe esse controlo à configuração de publicação de uma app. Uma configuração de publicação configura metadados que são usados para gerar resultados de tempo de publicação, como resultados da pesquisa ou respostas. Um controlo de publicação só afeta os pedidos publicados pela app se o controlo estiver anexado à configuração de publicação da app.

Alguns controlos, como os controlos de aumento, têm dependências de repositórios de dados. Se um repositório de dados for removido de uma app, todos os controlos dependentes do repositório de dados também são removidos dessa app e ficam inativos, mas não são eliminados.

Tipos de controlos de publicação

Estão disponíveis os seguintes tipos de controlos de publicação:

Controlo Descrição Disponível para
Controlo do aumento Altera a ordem dos resultados devolvidos Pesquise apps com armazenamentos de dados que suportam um esquema, como armazenamentos de dados que contêm dados estruturados ou dados não estruturados com metadados
Controlo de filtros Remove entradas dos resultados devolvidos Pesquise apps com armazenamentos de dados que suportam um esquema, como armazenamentos de dados que contêm dados estruturados ou dados não estruturados com metadados
Controlo de sinónimos Associa consultas entre si Pesquise apps com arquivos de dados estruturados ou não estruturados
Controlo de redirecionamento Redireciona para um URI especificado Todas as apps de pesquisa
Controlo de promoção Promove um link especificado para uma consulta Pesquise apps com arquivos de dados estruturados ou não estruturados

Acerca das condições

Quando cria um controlo, pode definir opcionalmente uma condição que determine quando o controlo é aplicado. As condições são definidas através de campos de condição. Os seguintes campos de condições estão disponíveis:

  • queryTerms. Um controlo opcional que é aplicado quando são pesquisadas consultas específicas. Quando a condição queryTerms é usada, o controlo é 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 está definido como SOLUTION_TYPE_SEARCH. É possível especificar até 10 queryTerms diferentes num único Control.condition. Se não forem especificados termos de consulta, o campo queryTerms é ignorado.

    Para criar com êxito um controlo de promoção, tem de especificar o campo queryTerms com fullMatch definido como true ou false.

  • activeTimeRange. Um controlo opcional que é aplicado quando ocorre um pedido num intervalo de tempo especificado. Verifica se a hora em que um pedido foi recebido está entre activeTimeRange.startTime e activeTimeRange.endTime. É possível especificar até 10 intervalos de activeTimeRange num único Control.condition. Se o campoactiveTimeRange não estiver especificado, o campo é ignorado.

Se forem especificadas várias condições para um controlo, o controlo é aplicado ao pedido de pesquisa quando ambos os tipos de condições são cumpridos. Se forem especificados vários valores para a mesma condição, apenas um dos valores tem de corresponder para que essa condição seja satisfeita.

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 é cumprida para um pedido com SearchRequest.query="gShoe" ou um pedido com SearchRequest.query="gBoot", mas não é cumprida com SearchRequest.query="gSandal" nem qualquer outra string.

Se não forem especificadas condições, o controlo é sempre aplicado.

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

Crie e anexe controlos de publicação de aumentos

Um controlo de publicação de aumento é definido como um controlo com um boostAction.

Siga as instruções abaixo para criar um controlo de publicação de aumento.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento de [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • BOOST_VALUE: um número de vírgula flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são despromovidos (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 tem de cumprir. Se o documento corresponder a todos os requisitos, o aumento é aplicado. Caso contrário, não existe nenhuma alteração. Se este campo estiver vazio, o aumento é aplicado a todos os documentos no arquivo de dados. Para a sintaxe de filtragem, consulte o artigo Sintaxe de expressão de filtro. Nota: não é possível filtrar o campo do documento title.
    • DATA_STORE_RESOURCE_PATH: o caminho completo do recurso do armazenamento de dados cujos documentos devem ser otimizados por este controlo. O formato do caminho completo do recurso é projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Este arquivo de dados tem de estar anexado ao motor especificado no pedido.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de filtros

Um controlo de publicação de filtros é definido como um controlo com um filterAction.

Use as instruções seguintes para criar um controlo de publicação de filtros.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento de [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • FILTER: uma string que especifica os requisitos que o documento tem de cumprir. Se o documento corresponder a todos os requisitos, o documento é devolvido nos resultados. Caso contrário, o documento não é apresentado nos resultados. Para a sintaxe de filtragem, consulte o artigo Sintaxe das expressões de filtro. Para mais informações, consulte filterAction. Nota: não é possível filtrar o campo do documento title.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de sinónimos

Um controlo de publicação de sinónimos é definido como um controlo com um synonymsAction.

Use as instruções seguintes para criar um controlo de publicação de sinónimos.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento de [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • SYNONYMS_N: uma lista de strings associadas entre si, o que aumenta a probabilidade de cada uma apresentar resultados semelhantes. Embora seja mais provável que obtenha resultados semelhantes, quando pesquisa cada uma das entradas de sinónimos, pode não receber todos os resultados relevantes para todos os sinónimos associados. Tem de especificar, pelo menos, dois sinónimos e pode especificar até 100 sinónimos. Cada sinónimo tem de estar codificado em UTF-8 e em letras minúsculas. Não são permitidas strings duplicadas. Por exemplo, pode adicionar "pixel", "telemóvel Android" e "telemóvel Google" como sinónimos. Para mais informações, consulte synonymsAction.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de redirecionamentos

Um controlo de publicação de redirecionamentos permite redirecionar os utilizadores para um URI fornecido. Os controlos de redirecionamento são definidos como um controlo com um redirectAction.

Use as instruções seguintes para criar um controlo de publicação de redirecionamentos.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento de [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • CONDITION: um campo opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000]. Se FULL_MATCH_1 for true, este campo pode ter, no máximo, três termos separados por espaços.
      • FULL_MATCH: um valor booleano que indica se a consulta de pesquisa tem de corresponder exatamente ao termo de consulta. Quando definido como true, requer que o SearchRequest.query corresponda totalmente ao queryTerm.value. Quando definido como false, requer que SearchRequest.query contenha queryTerm.value como uma substring.
      • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
      • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • REDIRECT_URI_N: um URI para o qual é redirecionado. Pode ter um comprimento máximo de 2000 carateres. Por exemplo, se o valor do termo de consulta for "apoio técnico", pode definir um redirecionamento para a página de apoio técnico em vez de devolver (ou não devolver) resultados da pesquisa para "apoio técnico". Neste exemplo, o URI de redirecionamento passa a ser "https://www.example.com/support". Para mais informações, consulte redirectAction.

  3. Associe o controlo à configuração de publicação da app através do 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 dos controlos que criou no passo anterior.

Crie e anexe controlos de publicação de promoções

Um controlo de publicação de promoção permite-lhe apresentar um link como resultado promovido. Este controlo está disponível para apps de pesquisa com arquivos de dados estruturados ou não estruturados e apps de pesquisa combinadas.

Para que o controlo de promoção entre em vigor, tem de o anexar à configuração de publicação da app.

Os controlos de promoção são definidos através de um promoteAction.

Para criar com êxito um controlo de promoção, tem de especificar o campo queryTerms com fullMatch definido como true ou false.

Siga as instruções abaixo para criar um controlo de publicação de promoções.

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

  1. Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.

    1. Na Google Cloud consola, aceda à página Gemini Enterprise.

      Aceda a Apps

    2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

  2. Execute os seguintes comandos curl para criar os seus controlos.

    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 o seguinte:

    • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
    • APP_ID: o ID da app.
    • CONTROL_ID: um identificador exclusivo para o controlo. O ID pode conter [1-63] carateres que podem ser letras, dígitos, hífenes e sublinhados.
    • DISPLAY_NAME: o nome legível do controlo. A Google recomenda que este nome indique quando ou por que motivo usar o controlo. Tem de ser uma string codificada em UTF-8 com um comprimento de [1,128].
    • USE_CASE: tem de ser SEARCH_USE_CASE_SEARCH ou SEARCH_USE_CASE_BROWSE. Se SEARCH_USE_CASE_BROWSE for especificado, não é possível usar Condition.queryTerms na condição.
    • Condition: um objeto opcional que define quando o controlo deve ser aplicado. Contém os seguintes campos:
      • queryTerms:
        • VALUE: o valor de consulta específico com o qual estabelecer correspondência. É uma string UTF-8 em letras minúsculas com um comprimento de [1, 5000].
        • FULL_MATCH_TRUE|FALSE: um valor booleano para indicar se o termo de consulta tem de corresponder totalmente.
      • activeTimeRange:
        • START_TIMESTAMP: uma indicação de tempo no formato RFC 3339 UTC "Zulu" para indicar o início de um intervalo de tempo.
        • END_TIMESTAMP: uma data/hora no formato RFC 3339 UTC "Zulu" para indicar o fim de um intervalo de tempo.
    • 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. Este arquivo de dados tem de estar anexado ao motor especificado no pedido.

    • DOCUMENT_RESOURCE_PATH: um campo para especificar o caminho do recurso do documento a ser promovido. Tem de 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 Web a promover. Este título é apresentado no resultado da pesquisa.

    • URI: um campo para especificar o URI para onde o resultado da pesquisa direciona o utilizador. Tem de 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 é apresentado no resultado da pesquisa.

    A resposta contém IDs de controlo de promoções que tem de anexar ao controlo de promoções na sua app de pesquisa.

  3. Associe o controlo à configuração de publicação da app através do método engines.servingConfigs.patch. A ordem pela qual anexa o promoteControlIds no pedido seguinte é a ordem pela qual os resultados promocionais são devolvidos.

    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 dos controlos que recebeu no passo anterior.

O que se segue?