Endpoint di ricerca del segmento

Ultimo aggiornamento: 29 ottobre 2025
  • Argomenti:

Creato per:

  • Sviluppatore

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 dell'API Adobe Experience Platform Segmentation Service. Prima di continuare, consulta la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all'API, incluse le intestazioni richieste e la lettura delle chiamate API di esempio.

Oltre alle intestazioni richieste descritte nella sezione guida introduttiva, tutte le richieste all’endpoint di ricerca dei 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 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}
ParametriDescrizione
schema.name={SCHEMA}(Obbligatorio) Dove {SCHEMA} rappresenta il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, è supportato solo _xdm.context.segmentdefinition.
s={SEARCH_TERM}(Facoltativo) Dove {SEARCH_TERM} rappresenta una query conforme all'implementazione di Microsoft della sintassi di ricerca di Lucene. Se non viene specificato alcun termine di ricerca, verranno restituiti tutti i record associati a schema.name. Una spiegazione più dettagliata è disponibile nell'appendice di questo documento.

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}
ParametriDescrizione
schema.name={SCHEMA}(Obbligatorio) Dove {SCHEMA} contiene il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, è supportato solo _xdm.context.segmentdefinition.
namespace={NAMESPACE}(Obbligatorio) Dove {NAMESPACE} contiene lo spazio dei nomi in cui si desidera eseguire la ricerca.
s={SEARCH_TERM}(Facoltativo) Dove {SEARCH_TERM} contiene una query conforme all'implementazione di Microsoft della sintassi di ricerca Lucene. Se non viene specificato alcun termine di ricerca, verranno restituiti tutti i record associati a schema.name. Una spiegazione più dettagliata è disponibile nell'appendice di questo documento.
entityId={ENTITY_ID}(Facoltativo) Limita la ricerca alla cartella specificata, specificata con {ENTITY_ID}.
limit={LIMIT}(Facoltativo) Dove {LIMIT} rappresenta il numero di risultati di ricerca da restituire. Il valore predefinito è 50.
page={PAGE}(Facoltativo) Dove {PAGE} rappresenta il numero di pagina utilizzato per impaginare i risultati della query cercata. Il numero di pagina inizia da 0.

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}
ParametriDescrizione
schema.name={SCHEMA}(Obbligatorio) Dove {SCHEMA} contiene il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, è supportato solo _xdm.context.segmentdefinition.
namespace={NAMESPACE}(Obbligatorio) Dove {NAMESPACE} contiene lo spazio dei nomi in cui si desidera eseguire la ricerca.
entityId={ENTITY_ID}(Obbligatorio) ID dell'oggetto di ricerca di cui si desidera ottenere le informazioni strutturali, specificato con {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"
    }
}