Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Connessione a Kustomer Kustomer è una potente piattaforma per l'esperienza dei clienti che riunisce tutto ciò di cui hai bisogno per servire meglio i tuoi clienti in un unico strumento. easy-to-use **Topics** + [AWS Glue supporto per Kustomer](kustomer-support.md) + [Policy contenenti le operazioni API per creare e utilizzare le connessioni](kustomer-configuring-iam-permissions.md) + [Configurazione di Kustomer](kustomer-configuring.md) + [Configurazione delle connessioni Kustomer](kustomer-configuring-connections.md) + [Lettura da entità Kustomer](kustomer-reading-from-entities.md) + [Opzioni di connessione Kustomer](kustomer-connection-options.md) + [Limitazioni Kustomer](kustomer-connection-limitations.md) # AWS Glue supporto per Kustomer AWS Glue supporta Kustomer come segue: **Supportato come origine?** Sì. È possibile utilizzare i job AWS Glue ETL per interrogare i dati di Kustomer. **Supportato come destinazione?** No. **Versioni API Kustomer supportate** Sono supportate le seguenti versioni API di Kustomer: + v1 # Policy contenenti le operazioni API per creare e utilizzare le connessioni La seguente policy di esempio descrive le autorizzazioni AWS IAM richieste per la creazione e l'utilizzo delle connessioni. Se si sta creando un nuovo ruolo, creare una policy che contenga quanto segue: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ In alternativa, se non desideri utilizzare il metodo precedente, utilizza le seguenti policy IAM gestite: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole)— Garantisce l'accesso alle risorse che AWS Glue i vari processi richiedono per l'esecuzione per conto dell'utente. Queste risorse includono AWS Glue Amazon S3, IAM, CloudWatch Logs e Amazon. EC2 Se segui la convenzione di denominazione delle risorse specificata in questa politica, AWS Glue i processi dispongono delle autorizzazioni richieste. Questa policy è in genere collegata ai ruoli specificati quando si definiscono crawler, processi ed endpoint di sviluppo. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess)— Concede l'accesso completo alle AWS Glue risorse quando un'identità a cui è allegata la policy utilizza la AWS console di gestione. Se si segue la convenzione per la denominazione per le risorse specificate nella policy, gli utenti hanno la piena funzionalità della console. Questa policy è in genere associata agli utenti della AWS Glue console. # Configurazione di Kustomer Prima di poterli utilizzare AWS Glue per trasferire dati da Kustomer alle destinazioni supportate, devi soddisfare questi requisiti: ## Requisiti minimi I requisiti minimi sono i seguenti: + Hai un account con Kustomer che contiene i dati che desideri trasferire. + Nelle impostazioni del tuo account, hai creato una chiave API. Per ulteriori informazioni, consulta [Creazione di una chiave API](#kustomer-configuring-creating-an-api-key). + Fornisci la chiave API a AWS Glue durante la creazione della connessione. Se soddisfi questi requisiti, sei pronto per connetterti AWS Glue al tuo account Kustomer. ## Creazione di una chiave API Per creare una chiave API da utilizzare per creare una connessione per il connettore Kustomer in Studio: AWS Glue 1. Accedi alla [dashboard di Kustomer utilizzando le tue credenziali.](https://amazon-appflow.kustomerapp.com/login) 1. Scegli l'icona **Impostazioni** dal menu a sinistra. 1. Espandi il menu a discesa **Sicurezza** e seleziona **Chiavi API**. 1. Nella pagina di creazione della chiave API, seleziona **Aggiungi una chiave API** nell'angolo in alto a destra. 1. Compila gli input obbligatori per la chiave API che stai creando. + Nome: qualsiasi nome per la chiave API. + Ruoli: 'org' deve essere selezionato per far funzionare APIs Kustomer. + Scadenza (in giorni): il numero di giorni in cui desideri che la chiave API sia valida. Puoi conservarlo come **Non scade mai**, se lo ritieni adatto al tuo caso d'uso. 1. Scegli **Create** (Crea). 1. Memorizza il valore della chiave API (token) per un ulteriore utilizzo per creare una connessione per il connettore Kustomer in Studio. AWS Glue # Configurazione delle connessioni Kustomer Per configurare una connessione Kustomer: 1. In AWS Secrets Manager, crea un segreto con i seguenti dettagli: 1. Per le app connesse gestite dal cliente, il segreto deve contenere l'app connessa Consumer Secret con `apiKey` come chiave. 1. Nota: devi creare un segreto per le tue connessioni in AWS Glue. 1. In AWS Glue Glue Studio, crea una connessione in **Connessioni dati** seguendo i passaggi seguenti: 1. In **Connessioni**, scegli **Crea connessione**. 1. Quando selezioni un'**origine dati**, seleziona Kustomer. 1. Seleziona il ruolo AWS IAM che AWS Glue può assumere e dispone delle autorizzazioni per le seguenti azioni: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Seleziona quello `secretName` che desideri utilizzare per questa connessione per AWS Glue inserire i token. 1. Selezionare le opzioni di rete se si desidera utilizzare la propria rete. 1. Concedi il permesso di lettura `secretName` al ruolo IAM associato al tuo AWS Glue lavoro. # Lettura da entità Kustomer **Prerequisito** Un oggetto Kustomer da cui si desidera leggere. È necessario il nome dell'oggetto, come Marchi o Schede. Nella tabella seguente sono illustrate le entità supportate. **Entità supportate come origine**: | Entità | Può essere filtrato | Supporta limite | Supporta Ordina per | Supporta Seleziona \$1 | Supporta il partizionamento | | --- | --- | --- | --- | --- | --- | | Marchi | No | Sì | No | Sì | No | | Schede | No | Sì | No | Sì | No | | Impostazioni chat | No | No | No | Sì | No | | Aziende | Sì | Sì | Sì | Sì | Sì | | Conversazioni | Sì | Sì | Sì | Sì | Sì | | Clienti | Sì | Sì | Sì | Sì | Sì | | Ricerche ancorate dei clienti | No | Sì | No | Sì | No | | Posizione di ricerca del cliente | No | No | No | Sì | No | | Hook e-mail | No | Sì | No | Sì | No | | Hook Web | No | Sì | No | Sì | No | | Articoli KB | No | Sì | No | Sì | No | | Categorie KB | No | Sì | No | Sì | No | | Moduli KB | No | Sì | No | Sì | No | | Percorsi KB | No | Sì | No | Sì | No | | Tag KB | No | Sì | No | Sì | No | | Modelli KB | No | Sì | No | Sì | No | | Temi KB | No | Sì | No | Sì | No | | Klasses | No | Sì | No | Sì | No | | KViews | No | Sì | No | Sì | No | | Messaggi | Sì | Sì | Sì | Sì | Sì | | Note | Sì | Sì | Sì | Sì | Sì | | Notifications | No | Sì | No | Sì | No | **Esempio**: ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "brands", "API_VERSION": "v1" } ``` ## Dettagli dell'entità e del campo di Kustomer Per ulteriori informazioni sui dettagli dell'entità e del campo, consultare: + [Marchi](https://api.kustomerapp.com/v1/brands) + [Carte](https://api.kustomerapp.com/v1/cards) + [Impostazioni chat](https://api.kustomerapp.com/v1/chat/settings) + [Aziende](https://api.kustomerapp.com/v1/companies) + [Conversazioni](https://api.kustomerapp.com/v1/conversations) + [Clienti](https://api.kustomerapp.com/v1/customers) + [Ricerche ancorate dei clienti](https://api.kustomerapp.com/v1/customers/searches/pinned) + [Posizione di ricerca del cliente](https://api.kustomerapp.com/v1/customers/searches/positions) + [Hook e-mail](https://api.kustomerapp.com/v1/hooks/email) + [Hook Web](https://api.kustomerapp.com/v1/hooks/web) + [Articoli KB](https://api.kustomerapp.com/v1/kb/articles) + [Categorie KB](https://api.kustomerapp.com/v1/kb/categories) + [Moduli KB]( https://api.kustomerapp.com/v1/kb/forms) + [Percorsi KB](https://api.kustomerapp.com/v1/kb/routes) + [Tag KB](https://api.kustomerapp.com/v1/kb/tags) + [Modelli KB](https://api.kustomerapp.com/v1/kb/templates) + [Temi KB](https://api.kustomerapp.com/v1/kb/themes) + [Klasses](https://api.kustomerapp.com/v1/klasses) + [KViews](https://api.kustomerapp.com/v1/kviews) + [Messaggi](https://api.kustomerapp.com/v1/messages) + [Note](https://api.kustomerapp.com/v1/notes) + [Notifiche](https://api.kustomerapp.com/v1/notifications) API Kustomer v1 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/glue/latest/dg/kustomer-reading-from-entities.html) ## Query di partizionamento **Partizionamento basato sul campo** Puoi fornire le opzioni Spark aggiuntive `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` e `NUM_PARTITIONS` se desideri utilizzare la concorrenza in Spark. Con questi parametri, la query originale viene suddivisa in `NUM_PARTITIONS` query secondarie che possono essere eseguite contemporaneamente dalle attività Spark. + `PARTITION_FIELD`: il nome del campo da utilizzare per partizionare la query. + `LOWER_BOUND`: un valore limite inferiore **inclusivo** del campo di partizione scelto. Per il DateTime campo, accettiamo il valore in formato ISO. Esempio di valore valido: ``` "2023-01-15T11:18:39.205Z" ``` + `UPPER_BOUND`: un valore limite superiore **esclusivo** del campo di partizione scelto. + `NUM_PARTITIONS`: il numero di partizioni. I dettagli di supporto del campo di partizionamento per entità sono riportati nella tabella seguente: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/glue/latest/dg/kustomer-reading-from-entities.html) Esempio: ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "conversation", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2023-01-15T11:18:39.205Z" "UPPER_BOUND": "2023-02-15T11:18:39.205Z" "NUM_PARTITIONS": "2" } ``` # Opzioni di connessione Kustomer Di seguito sono riportate le opzioni di connessione per Kustomer: + `ENTITY_NAME`(String): (obbligatorio) utilizzato per la lettura. Il nome dell'oggetto in Kustomer. + `API_VERSION`(String): (obbligatorio) utilizzato per la lettura. Versione di Rest API di Kustomer da utilizzare. + `SELECTED_FIELDS`(List): predefinito: vuoto (SELECT \$1). Utilizzato per la lettura. Colonne da selezionare per l'oggetto. + `FILTER_PREDICATE`(Stringa): predefinito: vuoto. Utilizzato per la lettura. Dev'essere in formato Spark SQL. + `QUERY`(Stringa): predefinito: vuoto. Utilizzato per la lettura. Query Spark SQL completa. + `PARTITION_FIELD`(Stringa): utilizzato per la lettura. Campo da utilizzare per partizionare la query. + `LOWER_BOUND`(Stringa): utilizzato per la lettura. Un valore limite inferiore inclusivo del campo di partizione scelto. + `UPPER_BOUND`(Stringa): utilizzato per la lettura. Un valore limite superiore esclusivo del campo di partizione scelto. + `NUM_PARTITIONS`(Numero intero): predefinito: 1. Utilizzato per la lettura. Numero di partizioni da leggere. + `INSTANCE_URL`(Stringa): (obbligatorio) utilizzato per la lettura. URL dell'istanza del cliente. # Limitazioni Kustomer Di seguito sono riportate le limitazioni o le note di Kustomer: + L'entità `Customer Searches` non è supportata poiché la documentazione dell'API Kustomer non ne ha dichiarato alcun endpoint. + Il supporto della filtrazione e del trasferimento incrementale sull'entità `Klasses` non è supportato. + Order By può essere supportato su più campi applicabili in un'unica richiesta. Tuttavia, è stato osservato che l'ordine per funzionalità su più campi si comporta in modo incoerente dal lato SaaS per alcune combinazioni. È imprevedibile in quanto potrebbero esserci “n” combinazioni che possono mostrare risultati di ordinamento errati. Esempio: Per l'entità `Customers`, Order By `progressiveStatus desc, name asc` non produce il risultato ordinato corretto. Viene ordinato solo in base all'ordine `progressiveStatus`. Se si osserva tale comportamento, è possibile utilizzare un singolo campo in base al quale ordinare. + Order By sul campo “ID” è supportato solo dalle entità `Conversations` e `Messages` come parametro di query. Ad esempio: https://api.kustomerapp.com/v1/ conversazioni? sort=desc (Ordina i risultati per 'id' in ordine decrescente). Inoltre, qualsiasi altro filtro o ordinamento su qualsiasi altro campo viene tradotto in un corpo di richiesta POST con l'endpoint API POST https://api.kustomerapp.com/v1/ customers/search. Per consentire il supporto dell'ordinamento per «id» in `Conversations` e`Messages`, dovrebbe essere presente solo l'ordine per id o qualsiasi altro filtro ordinato per ogni altro campo applicabile. and/or + Kustomer consente di recuperare un massimo di 10.000 record indipendentemente da una richiesta filtrata o non filtrata. A causa di questa limitazione, si verificherà una perdita di dati per qualsiasi entità che detenga più di 10.000 record. Esistono due possibili soluzioni alternative che è possibile eseguire per mitigare parzialmente questo problema: + Applica filtri per recuperare un set specifico di record. + Se ci sono più di 10.000 record con un filtro applicato, applica un valore di filtro successivo in una nuova richiesta successiva o applica intervalli nei filtri. Esempio: filterExpression della prima richiesta: `modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z` Si supponga che questo esaurisca il limite di record di 10.000. Un'altra richiesta può essere attivata con filterExpression: `modifiedAt >= 2023-03-15T05:26:23.000Z` + Come comportamento SaaS, l'operatore `CONTAINS` di Kustomer supporta la corrispondenza solo su parole complete e non le corrispondenze parziali all'interno di una parola. Ad esempio: “body CONTAINS 'test record'” corrisponderà a un record con 'test' nel campo 'body'. Tuttavia, «body CONTAINS 'test'» non corrisponderà a un record con '' nel campo testAnotherRecord 'body'.