A Pesquisa de segmento é usada para pesquisar campos contidos em várias fontes de dados e retorná-los em tempo quase real.
Este guia fornece informações para ajudá-lo a entender melhor a Pesquisa de segmento e inclui exemplos de chamadas de API para executar ações básicas usando a API.
Os endpoints usados neste guia fazem parte do Adobe Experience Platform Segmentation Service API. Antes de continuar, reveja o guia de introdução para obter informações importantes que você precisa saber para fazer chamadas para a API com sucesso, incluindo cabeçalhos necessários e como ler chamadas de API de exemplo.
Além dos cabeçalhos necessários descritos na seção de introdução, todas as solicitações para o endpoint de Pesquisa de segmento exigem o seguinte cabeçalho adicional:
Esse endpoint de pesquisa pode ser usado para pesquisar em vários namespaces, retornando uma lista de resultados de contagem de pesquisa. Vários parâmetros podem ser usados, separados por "E" comercial (&).
Formato da API
GET /search/namespaces?schema.name={SCHEMA}
GET /search/namespaces?schema.name={SCHEMA}&s={SEARCH_TERM}
Parâmetros | Descrição |
---|---|
schema.name={SCHEMA} |
(Obrigatório) Onde {SCHEMA} representa o valor da classe de esquema associado aos objetos de pesquisa. Atualmente, somente _xdm.context.segmentdefinition é compatível. |
s={SEARCH_TERM} |
(Opcional) Onde {SEARCH_TERM} representa uma consulta que está em conformidade com a implementação Microsoft de Sintaxe de pesquisa de Lucene. Se nenhum termo de pesquisa for especificado, todos os registros associados a schema.name será retornada. Uma explicação mais detalhada pode ser encontrada no apêndice deste documento. |
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/search/namespaces?schema.name=_xdm.context.segmentdefinition \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com as seguintes informações.
{
"namespaces": [
{
"namespace": "AAMTraits",
"displayName": "AAMTraits",
"count": 45
},
{
"namespace": "AAMSegments",
"displayName": "AAMSegment",
"count": 10
},
{
"namespace": "SegmentsAISegments",
"displayName": "SegmentSAISegment",
"count": 3
}
],
"totalCount": 3,
"status": {
"message": "Success"
}
}
Esse endpoint de pesquisa pode ser usado para recuperar uma lista de todos os objetos indexados de texto completo dentro do namespace especificado. Vários parâmetros podem ser usados, separados por "E" comercial (&).
Formato da API
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}&s={SEARCH_TERM}
GET /search/entities?schema.name={SCHEMA}&namespace={NAMESPACE}&entityId={ENTITY_ID}
Parâmetros | Descrição |
---|---|
schema.name={SCHEMA} |
(Obrigatório) Onde {SCHEMA} contém o valor da classe de esquema associado aos objetos de pesquisa. Atualmente, somente _xdm.context.segmentdefinition é compatível. |
namespace={NAMESPACE} |
(Obrigatório) Onde {NAMESPACE} contém o namespace no qual você deseja pesquisar. |
s={SEARCH_TERM} |
(Opcional) Onde {SEARCH_TERM} contém uma consulta que está em conformidade com a implementação Microsoft de Sintaxe de pesquisa de Lucene. Se nenhum termo de pesquisa for especificado, todos os registros associados a schema.name será retornada. Uma explicação mais detalhada pode ser encontrada no apêndice deste documento. |
entityId={ENTITY_ID} |
(Opcional) Limita sua pesquisa a na pasta designada, especificada com {ENTITY_ID}. |
limit={LIMIT} |
(Opcional) Onde {LIMIT} representa o número de resultados de pesquisa a serem retornados. O valor padrão é 50. |
page={PAGE} |
(Opcional) Onde {PAGE} representa o número de página usado para paginar resultados da consulta pesquisada. Observe que o número da página começa em 0. |
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/search/entities?schema.name=_xdm.context.segmentdefinition&namespace=AAMSegments \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com resultados correspondentes à consulta de pesquisa.
{
"entities": [
{
"id": "1012667",
"base64EncodedSourceId": "RFVGamdydHpEdy01ZTE1ZGJlZGE4YjAxMzE4YWExZWY1MzM1",
"sourceId": "DUFjgrtzDw-5e15dbeda8b01318aa1ef533",
"isFolder": true,
"parentFolderId": "974139",
"name": "aam-47995 verification (100)"
},
{
"id": "14653311",
"base64EncodedSourceId": "REVGamduLVgzdy01ZTE2ZjRhNjc1ZDZhMDE4YThhZDM3NmY1",
"sourceId": "DEFjgn-X3w-5e16f4a675d6a018a8ad376f",
"isFolder": false,
"parentFolderId": "324050",
"name": "AAM - Heavy equipment",
"description": "AAM - Acme Equipment"
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"pageOffset": 0,
"pageSize": 10
},
"status": {
"message": "Success"
}
}
Esse endpoint de pesquisa pode ser usado para obter as informações estruturais sobre o objeto de pesquisa solicitado.
Formato da API
GET /search/taxonomy?schema.name={SCHEMA}&namespace={NAMESPACE}&entityId={ENTITY_ID}
Parâmetros | Descrição |
---|---|
schema.name={SCHEMA} |
(Obrigatório) Onde {SCHEMA} contém o valor da classe de esquema associado aos objetos de pesquisa. Atualmente, somente _xdm.context.segmentdefinition é compatível. |
namespace={NAMESPACE} |
(Obrigatório) Onde {NAMESPACE} contém o namespace no qual você deseja pesquisar. |
entityId={ENTITY_ID} |
(Obrigatório) A ID do objeto de pesquisa sobre o qual você deseja obter as informações estruturais, especificadas com {ENTITY_ID}. |
Solicitação
curl -X GET \
https://platform.adobe.io/data/core/ups/search/taxonomy?schema.name=_xdm.context.segmentdefinition&namespace=AAMSegments&entityId=porsche11037 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'x-ups-search-version: 1.0'
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com informações estruturais detalhadas sobre o objeto de pesquisa solicitado.
{
"taxonomy": [
{
"id": "0",
"base64EncodedSourceId": "RFVGZ01BLTVlNjgzMGZjMzk3YjQ1MThhYWExYTA4Zg2",
"name": "AAMTraits for Cars",
"parentFolderId": "root"
},
{
"id": "150561",
"base64EncodedSourceId": "RFVGamdpRk1BZy01ZTY4MzBmYzM5N2I0NTE4YWFhMWEwOGY1",
"name": "Fast Cars",
"parentFolderId": "carTraits"
},
{
"id": "porsche11037",
"base64EncodedSourceId": "REFGZ01CLTVlNjczMGZjMzk3YjQ1MThhZGIxYTA4Zg==",
"name": "Porsche",
"parentFolderId": "redCarsFolderId"
}
],
"status": {
"message": "Success"
}
}
Após a leitura deste guia, você tem uma melhor compreensão de como a Pesquisa de segmento funciona.
As seções a seguir fornecem informações adicionais sobre como os termos de pesquisa funcionam. As consultas de pesquisa são gravadas da seguinte maneira: s={FieldName}:{SearchExpression}
. Assim, por exemplo, para procurar um segmento chamado AAM ou Platform, você usaria a seguinte consulta de pesquisa: s=segmentName:AAM%20OR%20Platform
.
!![NOTE] Para práticas recomendadas, a expressão de pesquisa deve ser codificada em HTML, como o exemplo mostrado acima.
A tabela a seguir lista os campos que podem ser pesquisados no parâmetro de consulta de pesquisa.
Nome do campo | Descrição |
---|---|
folderId | A pasta ou pastas que têm a ID da pasta da pesquisa especificada. |
folderLocation | O local ou locais que têm o local da pasta da pesquisa especificada. |
parentFolderId | O segmento ou a pasta que tem a ID da pasta principal da pesquisa especificada. |
segmentId | O segmento corresponde à ID de segmento da pesquisa especificada. |
segmentName | O segmento corresponde ao nome do segmento de sua pesquisa especificada. |
segmentDescription | O segmento corresponde à descrição do segmento de sua pesquisa especificada. |
A tabela a seguir lista as especificações de como as consultas de pesquisa funcionam ao usar a API de pesquisa de segmento.
!![NOTE] Os exemplos a seguir são mostrados em um formato não codificado em HTML para maior clareza. Para práticas recomendadas, codifique a expressão de pesquisa no HTML.
Exemplo de expressão de pesquisa | Descrição |
---|---|
fofo | Procure qualquer palavra. Isso retornará resultados se a palavra "foo" for encontrada em qualquer um dos campos pesquisáveis. |
foo E barra | Uma pesquisa booleana. Isso retornará resultados se both as palavras "foo" e "bar" são encontradas em qualquer um dos campos pesquisáveis. |
barra OU rodapé | Uma pesquisa booleana. Isso retornará resultados se ou a palavra "foo" ou a palavra "bar" são encontradas em qualquer um dos campos pesquisáveis. |
barra FOTO NÃO | Uma pesquisa booleana. Isso retornará resultados se a palavra "foo" for encontrada, mas a palavra "bar" não for encontrada em nenhum dos campos pesquisáveis. |
name: foo E barra | Uma pesquisa booleana. Isso retornará resultados se both as palavras "foo" e "bar" são encontradas no campo "name". |
executar* | Uma pesquisa curinga. Usar um asterisco (*) corresponde a 0 ou mais caracteres, o que significa que retornará resultados se o conteúdo de qualquer um dos campos pesquisáveis contiver uma palavra que começa com "executar". Por exemplo, isso retornará resultados se as palavras "executa", "executando", "runner" ou "runt" forem exibidas. |
câmara? | Uma pesquisa curinga. Usar um ponto de interrogação (?) corresponde somente a um caractere, o que significa que retornará resultados se o conteúdo de qualquer um dos campos pesquisáveis começar com "cam" e uma letra adicional. Por exemplo, isso retornará resultados se as palavras "camp" ou "cams" forem exibidas, mas não retornará resultados se as palavras "câmera" ou "campfire" forem exibidas. |
"guarda-chuva azul" | Uma pesquisa de frase. Isso retornará resultados se o conteúdo de qualquer um dos campos pesquisáveis contiver a frase completa "guarda-chuva azul". |
azul~ | Uma busca difusa. Como opção, você pode colocar um número entre 0 e 2 após o til (~) para especificar a distância de edição. Por exemplo, "blue~1" retornaria "blue", "blues" ou "cola". Pesquisa difusa only ser aplicada a termos, não frases. No entanto, é possível anexar til ao final de cada palavra em uma frase. Por exemplo, "acampar~ em~ no~ verão~" seria igual a "acampar no verão". |
"aeroporto de hotel"~5 | Uma pesquisa de proximidade. Esse tipo de pesquisa é usado para localizar termos próximos um do outro em um documento. Por exemplo, a frase "hotel airport"~5 O encontrará os termos “hotel” e “aeroporto” em até 5 palavras de distância em um documento. |
/a[0-9]+b$/ |
Uma pesquisa de expressão regular. Esse tipo de pesquisa encontra uma correspondência com base no conteúdo entre barras para frente "/", conforme documentado na classe RegExp. Por exemplo, para localizar documentos contendo "motel" ou "hotel", especifique /[mh]otel/ . Pesquisas de expressões regulares são comparadas com palavras únicas. |
Para obter documentação mais detalhada sobre a sintaxe de consulta, leia a Documentação da sintaxe de consulta do Lucene.