Endpoint di ricerca del segmento

La ricerca dei segmenti viene utilizzata per cercare i campi contenuti in diverse origini dati e restituirli quasi in tempo reale.

Questa guida fornisce informazioni utili per comprendere meglio la Ricerca di segmenti e include chiamate API di esempio per eseguire azioni di base utilizzando l’API.

Introduzione

Gli endpoint utilizzati in questa guida fanno parte del Adobe Experience Platform Segmentation Service API. Prima di continuare, controlla guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all’API, incluse le intestazioni richieste e la lettura di esempi di chiamate API.

Oltre alle intestazioni richieste descritte nella sezione guida introduttiva, tutte le richieste all’endpoint di ricerca dei segmenti richiedono la seguente intestazione aggiuntiva:

Ricerca in più spazi dei nomi

Questo endpoint di ricerca può essere utilizzato per eseguire ricerche in vari spazi dei nomi, restituendo un elenco di risultati del conteggio delle ricerche. È possibile utilizzare più parametri, separati da e commerciali (&).

Formato API

GET /search/namespaces?schema.name={SCHEMA}
GET /search/namespaces?schema.name={SCHEMA}&s={SEARCH_TERM}

Richiesta

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'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con le seguenti informazioni.

{
  "namespaces": [
    {
      "namespace": "AAMTraits",
      "displayName": "AAMTraits",
      "count": 45
    },
    {
      "namespace": "AAMSegments",
      "displayName": "AAMSegment",
      "count": 10
    },
    {
      "namespace": "SegmentsAISegments",
      "displayName": "SegmentSAISegment",
      "count": 3
    }
  ],
  "totalCount": 3,
  "status": {
    "message": "Success"
  }
}

Ricerca di singole entità

Questo endpoint di ricerca può essere utilizzato per recuperare una lista di tutti gli oggetti indicizzati full-text all’interno dello spazio dei nomi specificato. È possibile utilizzare più parametri, separati da e commerciali (&).

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

Richiesta

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'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 e i risultati corrispondono alla query di ricerca.

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

Ottenere informazioni strutturali su un oggetto di ricerca

Questo endpoint di ricerca può essere utilizzato per ottenere informazioni strutturali sull'oggetto di ricerca richiesto.

Formato API

GET /search/taxonomy?schema.name={SCHEMA}&namespace={NAMESPACE}&entityId={ENTITY_ID}

Richiesta

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'

Risposta

Una risposta corretta restituisce lo stato HTTP 200 con informazioni strutturali dettagliate sull’oggetto di ricerca richiesto.

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

Passaggi successivi

Dopo aver letto questa guida hai acquisito una migliore comprensione del funzionamento della ricerca per segmenti.

Appendice appendix

Le sezioni seguenti forniscono informazioni aggiuntive sul funzionamento dei termini di ricerca. Le query di ricerca vengono scritte nel modo seguente: s={FieldName}:{SearchExpression}. Quindi, ad esempio, per cercare una definizione di segmento denominata AAM o Platform, utilizza la seguente query di ricerca: s=segmentName:AAM%20OR%20Platform.

Per best practice, l’espressione di ricerca deve essere codificata come HTML, come nell’esempio mostrato sopra.

Campi ricerca search-fields

Nella tabella seguente sono elencati i campi in cui è possibile eseguire ricerche nel parametro della query di ricerca.

Espressione di ricerca search-expression

Nella tabella seguente sono elencate le specifiche del funzionamento delle query di ricerca quando si utilizza l’API di ricerca dei segmenti.

Gli esempi seguenti sono mostrati in un formato non codificato da HTML per una maggiore chiarezza. Per best practice, HTML codifica l’espressione di ricerca.

Per la documentazione più dettagliata sulla sintassi della query, consulta Documentazione sulla sintassi delle query Lucene.