Endpoint di ricerca per segmenti

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

Questa guida fornisce informazioni utili per comprendere meglio la funzione di ricerca dei segmenti e include chiamate API di esempio per l’esecuzione di azioni di base tramite l’API.

Introduzione

Gli endpoint utilizzati in questa guida fanno parte dell’ API Adobe Experience Platform Segmentation Service . Prima di continuare, controlla la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente le chiamate all'API, comprese le intestazioni richieste e come leggere le chiamate API di esempio.

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

• x-ups-search-version: "1,0"

Ricerca in più spazi dei nomi

Questo endpoint di ricerca può essere utilizzato per la ricerca in vari namespace, restituendo un elenco di risultati del conteggio di ricerca. È possibile utilizzare più parametri, separati da e commerciale (&).

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: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'x-ups-search-version: 1.0' 

Risposta

Una risposta corretta 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 un elenco di tutti gli oggetti full text indicizzati all’interno dello spazio dei nomi specificato. È possibile utilizzare più parametri, separati da e commerciale (&).

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: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'x-ups-search-version: 1.0' 

Risposta

Una risposta corretta restituisce lo stato HTTP 200 con risultati corrispondenti 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 le 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: {IMS_ORG}' \
    -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 ora una migliore comprensione del funzionamento della ricerca dei segmenti.

Appendice

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

!![NOTE] Per le best practice, l’espressione di ricerca deve essere codificata in HTML, come nell’esempio precedente.

Campi di ricerca

Nella tabella seguente sono elencati i campi che è possibile cercare all’interno del parametro di query di ricerca.

Espressione di ricerca

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

!![NOTE] Gli esempi seguenti sono visualizzati in un formato non HTML codificato per una maggiore chiarezza. Per le best practice, l’HTML codifica l’espressione di ricerca.

Per una documentazione più dettagliata sulla sintassi della query, leggi la documentazione relativa alla sintassi della query Lucene.