# Conexión a Kustomer Kustomer es una potente plataforma de experiencia del cliente que reúne todo lo necesario para mejorar la atención en una herramienta fácil de usar. **Topics** + [Compatibilidad de AWS Glue con Kustomer](kustomer-support.md) + [Políticas que contienen las operaciones de la API para crear y usar conexiones](kustomer-configuring-iam-permissions.md) + [Configuración de Kustomer](kustomer-configuring.md) + [Configuración de las conexiones a Kustomer](kustomer-configuring-connections.md) + [Lectura de entidades de Kustomer](kustomer-reading-from-entities.md) + [Opciones de conexión a Kustomer](kustomer-connection-options.md) + [Limitaciones de Kustomer](kustomer-connection-limitations.md) # Compatibilidad de AWS Glue con Kustomer AWS Glue admite Kustomer de la siguiente manera: **¿Es compatible como origen?** Sí. Puede utilizar los trabajos de ETL de AWS Glue para consultar datos de Kustomer. **¿Es compatible como destino?** No. **Versiones de la API de Kustomer compatibles** Las siguientes versiones de la API de Kustomer son compatibles: + v1 # Políticas que contienen las operaciones de la API para crear y usar conexiones En el siguiente ejemplo de política se describen los permisos de AWS IAM necesarios para crear y utilizar conexiones. Si va a crear un nuevo rol, cree una política que contenga lo siguiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ Si no desea utilizar el método anterior, puede utilizar las siguientes políticas de IAM administradas: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole): da acceso a recursos que precisan diversos procesos de AWS Glue para ejecutarse en su nombre. Entre estos recursos se incluyen AWS Glue, Amazon S3, IAM, CloudWatch Logs y Amazon EC2. Si aplica la convención de nomenclatura en los recursos especificados en esta política, los procesos de AWS Glue tienen los permisos necesarios. Normalmente, esta política se asocia a los roles que se especifican a la hora de definir rastreadores, trabajos y puntos de conexión de desarrollo. + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess): otorga acceso total a los recursos de AWS Glue cuando una identidad a la que está asociada la política utiliza la Consola de administración de AWS. Si sigue la convención de nomenclatura para los recursos especificados en esta política, los usuarios dispondrán de todas las funciones de la consola. Esta política se suele adjuntar a los usuarios de la consola AWS Glue. # Configuración de Kustomer Antes de poder utilizar AWS Glue para transferir datos desde Kustomer a destinos compatibles, deberá cumplir estos requisitos: ## Requisitos mínimos Los requisitos mínimos son los siguientes: + Tener una cuenta en Kustomer que contenga los datos que desea transferir. + Haber creado la clave de API en la configuración de la cuenta. Para obtener más información, consulte [Creación de una clave de API](#kustomer-configuring-creating-an-api-key). + Se proporciona la clave de API a AWS Glue al crear la conexión. Si cumple estos requisitos, estará listo para conectar AWS Glue a la cuenta de Kustomer. ## Creación de una clave de API Para crear una clave de API que utilizará para crear una conexión para el conector de Kustomer en AWS Glue Studio: 1. Inicie sesión en el [panel de Kustomer con sus credenciales.](https://amazon-appflow.kustomerapp.com/login) 1. Elija el icono **Configuración** en el menú situado al costado izquierdo. 1. Amplíe el menú desplegable **Seguridad** y seleccione **Claves de API**. 1. En la página de creación de la clave de API, seleccione **Agregar una clave de API** en la esquina superior derecha. 1. Rellene las entradas obligatorias correspondientes a la clave de API que se va a crear. + Nombre: cualquier nombre para la clave de API. + Roles: se debe seleccionar “org” para que las API de Kustomer funcionen. + Caducará (en días): la cantidad de días durante los que desea que la clave de API permanezca válida. Puede establecer esta opción en **No caducará nunca**, si es lo que el caso de uso precisa. 1. Seleccione **Crear**. 1. Guarde el valor (token) de la clave de API para usarlo posteriormente a fin de crear una conexión para el conector de Kustomer en AWS Glue Studio. # Configuración de las conexiones a Kustomer Para configurar una conexión a Kustomer: 1. En AWS Secrets Manager, cree un secreto con los siguientes detalles: 1. En el caso de las aplicaciones conectadas administradas por el cliente, el secreto debe contener el secreto del consumidor de la aplicación conectada con `apiKey` como la clave. 1. Nota: Debe crear un secreto para las conexiones en AWS Glue. 1. En AWS Glue Glue Studio, cree una conexión en **Conexiones de datos** según los pasos que se indican a continuación: 1. En **Conexiones**, elija **Crear conexión**. 1. Al seleccionar un **Origen de datos**, elija Kustomer. 1. Seleccione el rol de AWS IAM que AWS Glue pueda asumir y que tenga permisos para las siguientes acciones: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. Seleccione el `secretName` que desee usar para esta conexión en AWS Glue para colocar los tokens. 1. Seleccione las opciones de red si quiere usar su red. 1. Conceda el rol de IAM asociado a su permiso de trabajo de AWS Glue para leer `secretName`. # Lectura de entidades de Kustomer **Requisito previo** Un objeto de Kustomer desde el que desea leer. Necesitará el nombre del objeto, como Marcas o Tarjetas. En la siguiente tabla se muestran las entidades admitidas. **Entidades compatibles como origen:** | Entidad | Se puede filtrar | Admite límite | Admite Ordenar por | Admite Seleccionar \$1 | Admite partición | | --- | --- | --- | --- | --- | --- | | Marcas | No | Sí | No | Sí | No | | Tarjetas | No | Sí | No | Sí | No | | Configuración del chat | No | No | No | Sí | No | | Empresas | Sí | Sí | Sí | Sí | Sí | | Conversaciones | Sí | Sí | Sí | Sí | Sí | | Clientes | Sí | Sí | Sí | Sí | Sí | | Búsquedas de clientes ancladas | No | Sí | No | Sí | No | | Posición de búsquedas de clientes | No | No | No | Sí | No | | Enlaces de correo | No | Sí | No | Sí | No | | Enlaces web | No | Sí | No | Sí | No | | Artículos de KB | No | Sí | No | Sí | No | | Categorías de KB | No | Sí | No | Sí | No | | Formularios de KB | No | Sí | No | Sí | No | | Rutas de KB | No | Sí | No | Sí | No | | Etiquetas de KB | No | Sí | No | Sí | No | | Plantillas de KB | No | Sí | No | Sí | No | | Temas de KB | No | Sí | No | Sí | No | | Klasses | No | Sí | No | Sí | No | | KViews | No | Sí | No | Sí | No | | Mensajes | Sí | Sí | Sí | Sí | Sí | | Notas | Sí | Sí | Sí | Sí | Sí | | Notificaciones | No | Sí | No | Sí | No | **Ejemplo:** ``` Kustomer_read = glueContext.create_dynamic_frame.from_options( connection_type="kustomer", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "brands", "API_VERSION": "v1" } ``` ## Detalles de entidades y campos de Kustomer Para obtener más información acerca de las entidades y los detalles de los campos, consulte: + [Marcas](https://api.kustomerapp.com/v1/brands) + [Tarjetas](https://api.kustomerapp.com/v1/cards) + [Configuración del chat](https://api.kustomerapp.com/v1/chat/settings) + [Empresas](https://api.kustomerapp.com/v1/companies) + [Conversaciones](https://api.kustomerapp.com/v1/conversations) + [Clientes](https://api.kustomerapp.com/v1/customers) + [Búsquedas de clientes ancladas](https://api.kustomerapp.com/v1/customers/searches/pinned) + [Posición de búsquedas de clientes](https://api.kustomerapp.com/v1/customers/searches/positions) + [Enlaces de correo](https://api.kustomerapp.com/v1/hooks/email) + [Enlaces web](https://api.kustomerapp.com/v1/hooks/web) + [Artículos de KB](https://api.kustomerapp.com/v1/kb/articles) + [Categorías de KB](https://api.kustomerapp.com/v1/kb/categories) + [Formularios de KB]( https://api.kustomerapp.com/v1/kb/forms) + [Rutas de KB](https://api.kustomerapp.com/v1/kb/routes) + [Etiquetas de KB](https://api.kustomerapp.com/v1/kb/tags) + [Plantillas de KB](https://api.kustomerapp.com/v1/kb/templates) + [Temas de KB](https://api.kustomerapp.com/v1/kb/themes) + [Klasses](https://api.kustomerapp.com/v1/klasses) + [KViews](https://api.kustomerapp.com/v1/kviews) + [Mensajes](https://api.kustomerapp.com/v1/messages) + [Notas](https://api.kustomerapp.com/v1/notes) + [Notificaciones](https://api.kustomerapp.com/v1/notifications) API v1 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/glue/latest/dg/kustomer-reading-from-entities.html) ## Consultas de partición **Partición basada en campos** Puede proporcionar las opciones adicionales de Spark `PARTITION_FIELD`, `LOWER_BOUND`, `UPPER_BOUND` y `NUM_PARTITIONS` si quiere utilizar la simultaneidad en Spark. Con estos parámetros, la consulta original se dividiría en un número `NUM_PARTITIONS` de subconsultas que las tareas de Spark pueden ejecutar simultáneamente. + `PARTITION_FIELD`: el nombre del campo que se utilizará para particionar la consulta. + `LOWER_BOUND`: un valor de límite inferior **inclusivo** del campo de partición elegido. Para el campo DateTime, aceptamos el valor en formato ISO. Ejemplo de valor válido: ``` "2023-01-15T11:18:39.205Z" ``` + `UPPER_BOUND`: un valor límite superior **exclusivo** del campo de partición elegido. + `NUM_PARTITIONS`: el número de particiones. En la siguiente tabla se detalla la compatibilidad de los campos de partición por entidad: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/glue/latest/dg/kustomer-reading-from-entities.html) Ejemplo: ``` 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" } ``` # Opciones de conexión a Kustomer Existen las siguientes opciones para establecer conexión con Kustomer: + `ENTITY_NAME`(cadena): (obligatorio) se usa para lectura. El nombre del objeto en Stripe. + `API_VERSION`(cadena): (obligatorio) se usa para lectura. Versión de la API de REST de Kustomer que desea usar. + `SELECTED_FIELDS`(lista): predeterminado: empty(SELECT \$1). Se usa para leer. Columnas que desee seleccionar para el objeto. + `FILTER_PREDICATE`(cadena): predeterminado: vacío. Se usa para leer. Debe estar en el formato de Spark SQL. + `QUERY`(cadena): predeterminado: vacío. Se usa para leer. Consulta completa de Spark SQL. + `PARTITION_FIELD`(cadena): se usa para lectura. Campo que se utilizará para particionar la consulta. + `LOWER_BOUND`(cadena): se usa para lectura. Un valor de límite inferior inclusivo del campo de partición elegido. + `UPPER_BOUND`(cadena): se usa para lectura. Un valor límite superior exclusivo del campo de partición elegido. + `NUM_PARTITIONS`(entero): predeterminado: 1. Se usa para leer. Número de particiones para leer. + `INSTANCE_URL`(cadena): (obligatorio) se usa para lectura. URL de la instancia de Kustomer. # Limitaciones de Kustomer Las siguientes son limitaciones o notas correspondientes a Kustomer: + La entidad `Customer Searches` no es compatible porque la documentación de la API de Kustomer no ha declarado ningún punto de conexión para esta. + No se admite la filtración ni la transferencia incremental en la entidad `Klasses`. + “Ordenar por” se puede admitir en varios campos aplicables en una sola solicitud. Sin embargo, se ha observado que la ordenación por funcionalidad en varios campos se comporta de manera inconsistente en el SaaS en algunas combinaciones. Es impredecible, ya que puede haber combinaciones “n” que podrían arrojar resultados de ordenación incorrectos. Por ejemplo: En el caso de la entidad `Customers`, “ordenar por `progressiveStatus desc, name asc`” no arroja el resultado correcto ordenado. Ordena únicamente en función del orden `progressiveStatus`. Si se observa este comportamiento, puede utilizar un único campo para ordenar. + “Ordenar por” en el campo ID solo es compatible con las entidades `Conversations` y `Messages` como parámetro de consulta. Por ejemplo: https://api.kustomerapp.com/v1/conversations?sort=desc (esto ordena los resultados por ID en orden descendente). Además, cualquier otro filtro u ordenación en cualquier otro campo se traduce en un cuerpo de solicitud POST, con el punto de conexión de la API como POST https://api.kustomerapp.com/v1/customers/search Para admitir la ordenación por ID en `Conversations` y `Messages`, solo debe estar presente la ordenación por ID o cualquier otro filtro u ordenación en cualquier otro campo aplicable. + Kustomer permite obtener un máximo de 10 000 registros, independientemente de si se trata de una solicitud filtrada o no filtrada. Debido a esta limitación, se perderán datos para cualquier entidad que tenga más de 10 000 registros. Existen dos soluciones alternativas que puede aplicar para mitigar parcialmente esta situación: + Aplique filtros para obtener un conjunto de registros específico. + Si hay más de 10 000 registros con un filtro aplicado, aplique un valor de filtro sucesivo en una nueva solicitud posterior o aplique rangos a los filtros. Por ejemplo: filterExpression de la primera solicitud: `modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z` Suponga que esto agota el límite de registro de 10 000. Se puede activar otra solicitud con filterExpression: `modifiedAt >= 2023-03-15T05:26:23.000Z` + Como comportamiento de SaaS, el operador `CONTAINS` de Kustomer solo admite coincidencias de palabras completas y no coincidencias parciales dentro de una palabra. Por ejemplo: “body CONTAINS 'test record'” coincidirá con un registro que contenga “test” en el campo “body”. Sin embargo, “body CONTAINS 'test'” no coincidirá con un registro que contenga “testAnotherRecord” en el campo “body”.