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.
Gli endpoint utilizzati in questa guida fanno parte del Adobe Experience Platform Segmentation Service API. 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:
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}
Parametri | Descrizione |
---|---|
schema.name={SCHEMA} |
(Obbligatorio) Dove {SCHEMA} rappresenta il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, solo _xdm.context.segmentdefinition è supportato. |
s={SEARCH_TERM} |
(Facoltativo) Dove {SEARCH_TERM} rappresenta una query conforme all'implementazione Microsoft di Sintassi di ricerca di Lucene. Se non viene specificato alcun termine di ricerca, tutti i record associati a schema.name verrà restituito. Una spiegazione più dettagliata può essere trovata nel appendice del presente 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
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"
}
}
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}
Parametri | Descrizione |
---|---|
schema.name={SCHEMA} |
(Obbligatorio) Dove {SCHEMA} contiene il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, solo _xdm.context.segmentdefinition è supportato. |
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 Microsoft di Sintassi di ricerca di Lucene. Se non viene specificato alcun termine di ricerca, tutti i record associati a schema.name verrà restituito. Una spiegazione più dettagliata può essere trovata nel appendice del presente documento. |
entityId={ENTITY_ID} |
(Facoltativo) Limita la ricerca all'interno della cartella designata, 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 della 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
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"
}
}
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}
Parametri | Descrizione |
---|---|
schema.name={SCHEMA} |
(Obbligatorio) Dove {SCHEMA} contiene il valore della classe dello schema associato agli oggetti di ricerca. Attualmente, solo _xdm.context.segmentdefinition è supportato. |
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"
}
}
Dopo aver letto questa guida hai ora una migliore comprensione del funzionamento della ricerca dei segmenti.
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.
Nella tabella seguente sono elencati i campi che è possibile cercare all’interno del parametro di query di ricerca.
Nome campo | Descrizione |
---|---|
folderId | Cartella o cartelle con l'ID cartella della ricerca specificata. |
folderLocation | La posizione o le posizioni in cui si trova la cartella della ricerca specificata. |
parentFolderId | Il segmento o la cartella con l’ID della cartella principale della ricerca specificata. |
segmentId | Il segmento corrisponde all’ID del segmento della ricerca specificata. |
segmentName | Il segmento corrisponde al nome del segmento della ricerca specificata. |
segmentDescription | Il segmento corrisponde alla descrizione del segmento della ricerca specificata. |
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 codificato di HTML per una maggiore chiarezza. Per le best practice, HTML codifica l’espressione di ricerca.
Espressione di ricerca di esempio | Descrizione |
---|---|
foo | Cerca qualsiasi parola. Se la parola "foo" si trova in uno qualsiasi dei campi ricercabili, verranno restituiti i risultati. |
bar e piedi | Una ricerca booleana. Questo restituirà i risultati se entrambi le parole "foo" e "bar" si trovano in uno qualsiasi dei campi ricercabili. |
barra dei piedi O | Una ricerca booleana. Questo restituirà i risultati se o la parola "foo" o la parola "bar" si trovano in uno qualsiasi dei campi ricercabili. |
barra NON | Una ricerca booleana. Questo restituisce i risultati se la parola "foo" è trovata ma la parola "bar" non è trovata in nessuno dei campi ricercabili. |
nome: bar e piedi | Una ricerca booleana. Questo restituirà i risultati se entrambi le parole "foo" e "bar" si trovano nel campo "name". |
run* | Ricerca con carattere jolly. L’utilizzo di un asterisco (*) corrisponde a 0 o più caratteri, ovvero restituisce risultati se il contenuto di uno dei campi ricercabili contiene una parola che inizia con "run". Ad esempio, questo restituirà i risultati se compaiono le parole "run", "running", "runner" o "runt". |
cam? | Ricerca con carattere jolly. Utilizzando un punto interrogativo (?) rileva esattamente un solo 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 restituisce i risultati se compaiono le parole "camp" o "cams", ma non restituisce i risultati se compaiono le parole "camera" o "campfire". |
"ombrello blu" | Ricerca di frasi. Questo restituisce i risultati se il contenuto di uno qualsiasi dei campi ricercabili contiene la frase completa "ombrello blu". |
blu~ | Una ricerca sfocata. Facoltativamente, è 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 "colla". Ricerca fuzzy può only essere applicati ai termini, non alle frasi. Tuttavia, è possibile aggiungere riquadri alla fine di ogni parola in una frase. Così, per esempio, "campeggio~ in~ the~ estate~" avrebbe una partita su "campeggio in estate". |
"hotel airport"~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$/ |
Una ricerca con espressione regolare. 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 con espressione regolare vengono confrontate con parole singole. |
Per una documentazione più dettagliata sulla sintassi della query, consulta la sezione Documentazione sulla sintassi della query Lucene.