Ponto de extremidade de Pesquisa de Segmento

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.

Introdução

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:

• x-ups-search-version: "1.0"

Pesquisar em vários namespaces

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}

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

Pesquisar entidades individuais

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}

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

Obter informações estruturais sobre um objeto de pesquisa

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}

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

Próximas etapas

Após a leitura deste guia, você tem uma melhor compreensão de como a Pesquisa de segmento funciona.

Apêndice

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.

Campos de pesquisa

A tabela a seguir lista os campos que podem ser pesquisados no parâmetro de consulta de pesquisa.

Expressão de pesquisa

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.

Para obter documentação mais detalhada sobre a sintaxe de consulta, leia a Documentação da sintaxe de consulta do Lucene.