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 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}
Elemento “parameters”
Descrizione
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}
Elemento “parameters”
Descrizione
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}
Elemento “parameters”
Descrizione
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"
    }
}

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 sono scritte nel modo seguente: s={FieldName}:{SearchExpression}. Ad esempio, per cercare una definizione di segmento denominata AAM o Platform, è necessario utilizzare la seguente query di ricerca: s=segmentName:AAM%20OR%20Platform.

Per le best practice, l'espressione di ricerca deve essere codificata come HTML, come nell'esempio precedente.

Cerca campo search-fields

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

Nome campo
Descrizione
folderId
Cartella o cartelle con l'ID cartella della ricerca specificata.
folderLocation
Il percorso o i percorsi in cui si trova la cartella della ricerca specificata.
parentFolderId
La definizione del segmento o la cartella che ha l’ID della cartella principale della ricerca specificata.
segmentId
La definizione del segmento che corrisponde all’ID del segmento della ricerca specificata.
segmentName
La definizione del segmento che corrisponde al nome del segmento della ricerca specificata.
segmentDescription
La definizione del segmento che corrisponde alla descrizione del segmento della ricerca specificata.

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 vengono visualizzati in un formato non codificato da HTML per una maggiore chiarezza. Per best practice, HTML codifica l’espressione di ricerca.

Espressione di ricerca di esempio
Descrizione
foo
Cerca qualsiasi parola. Questo restituirà i risultati se la parola "foo" si trova in uno qualsiasi dei campi ricercabili.
bar Foo AND
Una ricerca booleana. Questo restituirà risultati se entrambi le parole "foo" e "bar" si trovano in uno qualsiasi dei campi ricercabili.
barra o foo
Una ricerca booleana. Questo restituirà risultati se o la parola "foo" o la parola "bar" si trovano in uno qualsiasi dei campi ricercabili.
foo NOT bar
Una ricerca booleana. Questo restituirà i risultati se la parola "foo" viene trovata ma la parola "bar" non è trovata in nessuno dei campi ricercabili.
nome: foo AND bar
Una ricerca booleana. Questo restituirà i risultati se entrambi le parole "foo" e "bar" si trovano nel campo "name".
esecuzione*
Ricerca con caratteri jolly. L’asterisco (*) corrisponde a 0 o più caratteri, il che significa che restituirà risultati se il contenuto di uno dei campi ricercabili contiene una parola che inizia con "esegui". Ad esempio, questo restituirà i risultati se vengono visualizzate le parole "run", "running", "runner" o "runt".
Camma?
Ricerca con caratteri jolly. Utilizzo di un punto interrogativo (?) corrisponde esattamente a un carattere, il che significa che restituirà risultati se il contenuto di uno qualsiasi dei campi ricercabili inizia con "cam" e una lettera aggiuntiva. Ad esempio, questo restituirà i risultati se vengono visualizzate le parole "camp" o "cams", ma non i risultati se vengono visualizzate le parole "camera" o "campfire".
"ombrello blu"
Ricerca di frasi. Questo restituirà i risultati se il contenuto di uno qualsiasi dei campi ricercabili contiene la frase completa "ombrello blu".
blu~
Una ricerca confusa. In alternativa, è possibile inserire un numero compreso tra 0 e 2 dopo la tilde (~) per specificare la distanza di modifica. Ad esempio, "blue~1" restituirà "blue", "blues" o "glue". La ricerca fuzzy può essere applicata solo ai termini, non alle frasi. Tuttavia, è possibile aggiungere le tessere alla fine di ogni parola di una frase. Ad esempio, "camping~ in~ the~ summer~" corrisponderebbe a "camping in estate".
"aeroporto dell'hotel"~5
Una ricerca di prossimità. Questo tipo di ricerca viene utilizzato per trovare termini vicini tra loro in un documento. Ad esempio, la frase "hotel airport"~5 troverà i termini "hotel" e "aeroporto" entro 5 parole l'uno dall'altro in un documento.
/a[0-9]+b$/
Ricerca di espressioni regolari. Questo tipo di ricerca trova una corrispondenza basata sul contenuto tra barre "/", come documentato nella classe RegExp. Ad esempio, per trovare documenti contenenti "motel" o "hotel", specificare /[mh]otel/. Le ricerche di espressioni regolari vengono associate a singole parole.

Per una documentazione più dettagliata sulla sintassi della query, leggere la documentazione sulla sintassi della query Lucene.

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871