Perspectiva General

El API de datos es un servicio de ayuda para recuperar llamadas, mensajes y datos de aplicación. El archivo que usted puede recibir contiene información detallada sobre sus servicios programáticos. Las lecciones en este documento lo ayudarán a solicitar y acceder a los datos deseados, útiles para: 

 

  • solución de problemas en general
  • optimización de sus procesos
  • análisis del comportamiento y la experiencia del cliente
  • creación de nuevas soluciones para atender a sus clientes
  • ajuste de SmartFlows existentes en su experiencia del cliente

Perspectiva General: Uso de Insights API

 

  1. GET /_rest/v4/dwh/Q recupera una lista de campos por consultar. Use estos campos para diseñar una consulta. Puede encontrar una lista completa de campos desde la fecha de esta redacción en la lista de campos de consulta.
  2. POST /_rest/v4/dwh/Q valida y procesa su consulta. Se devuelve un GUID que debería ser almacenado para volverlo a usar en futuras llamadas. Este GUID es requerido para verificar el estado de su informe.

 

En su consulta, el campo ámbito (scope) limita los resultados a sesiones* (sessions) que coinciden con sus filtros

 

* Similar a la analítica web, una sesión correlaciona todas las acciones para 1 usuario dentro de 1 ejecución integral de un flujo

 

  1. La consulta se ejecuta
  2. GET /_rest/v4/dwh/Q/{guid}/status habilita la consulta del estado. Siga usando esta API hasta que el informe muestre el estado “Completado”
  3. HEAD /_rest/v4/dwh/Q/{guid} provee los encabezados HTTP asociados con su informe sin enviar el archivo.
  4. GET /_rest/v4/dwh/Q/{guid} descarga el archivo/informe
 

Ejemplo 1: Obtenga campos disponibles

Use esta API para obtener una lista de campos disponible para filtrar y organizar el informe

GET /_rest/v4/dwh/Q

(no parameters)

Headers:

Status: 200

Content-Type: application/json

Body:

{

"ApplicationExitEvent": {

   "fields": [

     "StartTime",

     "EndTime",

     "Path",

     "ExitReason"

   ]

},

"DtmfEvent": {

   "fields": [

     "DtmfInput",

     "DtmfSource",

     "ErrorReason"

   ]

}

}

Ejemplo 2: Envíe consulta

Use POST para validar y enviar su consulta. La consulta acepta un cuerpo JSON con 4 atributos principales:

 

timestamp

Requerido. Restringe el rango fecha/hora de registros por analizar durante todas las fases de filtrado y procesamiento. Si su consulta analizada (scoped) no está proporcionando la sesión completa, extienda el rango de su timestamp

 

data

Requerido. Identifique cuáles campos aparecerán en el final del informe

 

scope

Opcional. Provee la capacidad de filtrar y recoger los registros asociados. Limitado actualmente a sesiones. Por ejemplo, este atributo se usa para encontrar sesiones completas que coincidan con su propio atributo de filtros. El soporte para un alcance del ID de la Aplicación está bajo revisión.

 

– Si este atributo es usado, se debe proporcionar los sub-atributos filtros (filters) y alcance (scope).

 

– filters provee filtrado de sesión usando sintaxis de MongoDB:

 

    • $eq – igual a…
    • $gt – mayor que…
    • $gte – mayor que o igual a…
    • $lt – menor que…
    • $lte – menor que o igual a…
    • $ne – no igual a…

 

filters

Opcional. Incluye o excluye registros durante la fase final del filtrado y procesamiento. Solo se devolverán los datos con coincidencias.

 

  • Si se proporciona un filtro alcance (scope), entonces los filtros (filters) pueden excluir los registros individuales dentro de una sesión (session).

 

Ver Tutorial: Diseñe una consulta para más información.

Solicite todos los registros que coincidan explícitamente con los criterios. Esta es la consulta mínima aceptable.

 

Explicación: Este ejemplo limita sus datos a los registros que ocurren en o después de ($gte) 2019-11-25 y en o antes de ($lte) 2019-11-26. El informe solo tendrá 1 columna: FlowId

 

POST /_rest/v4/dwh/Q

Authorization: Bearer 0sjey2n81hamxis=/

Content-Type: application/json


{

"timestamp": {

   "$gte": "2019-11-25T00:00:00Z",

   "$lte": "2019-11-26T00:00:00Z"

},

"data": {

   "ApplicationExitEvent": {

       "fields": ["FlowId"]

   }

}

}

Headers:

Status: 201
Content-Type: application/json
Content-Length: 43

Body:

{
"id": "ae9faa8e3cee29e5185578ad028e29f2"
}

Solicite cualquier/todos los registros ApplicationExitEvent asociados con FlowId

5dcf48b453e0ab04386da7d1

 


POST /_rest/v4/dwh/Q

Authorization: Bearer 0sjey2n81hamxis=/

Content-Type: application/json


{

 "timestamp": {

   "$gte": "2019-11-25T00:00:00Z",

   "$lte": "2019-11-26T00:00:00Z"

 },

 "data": {

   "ApplicationExitEvent": {

     "fields": ["EventName", "EventVersion", "EventSku", "TimeStamp",

       "HostId", "CustomerId", "CustomerName", "Originator",

       "OriginatorId", "FlowId", "FlowName", "ActionId", "ActionName",

       "IsTriggerAction", "SessionId", "TransactionId",

       "ApplicationRegion", "PassthroughVersion", "Passthrough",

       "StartTime", "EndTime", "Path", "ExitReason"]

   }

 },

 "filters": {

   "ApplicationExitEvent": {

     "FlowId": {"$eq": "5dcf48b453e0ab04386da7d1"}

   }

 }

}

Headers:

Status: 201
Content-Type: application/json
Content-Length: 43

Body:

{
 "id": "8dc9054b258c51f9ecf1f69322d69f9"
}
Errores relacionados

Los siguientes errores pueden ocurrir debido al formato o sintaxis incorrectos en el cuerpo de la solicitud API de Consulta.

Dates should be in ISO-8601 format

Status: 400
{
  "code": 400,
  "message": {
    "Date_Filters": {
      "message": "Invalid date filters [2019-10-19 01:45:36.123Z]. They must be in ISO8601 format. Example: 'YYYY-MM-DDTHH:MM:SSZ'",
      "code": "422-6"
    }
  }
}

Available operators: ($eq, $gt, $gte, $lt, $lte, $ne)

Status: 400
{
  "code": 400,
  "message": {
    "Operators": "Invalid operators [gte, lte], try to use any of these ($gte, $lte, $gt, $lt, $ne, $eq)."
  }
}

Event names and fields are case sensitive and must match the values provided by Get Available Fields.

Status: 400
{
  "code": 400,
  "message": "Application ExitEvent is not a valid schema name."
}

Event names and fields are case sensitive and must match the values provided by Get Available Fields

Status: 400
{
  "code": 400,
  "message": "Flow Id is not a valid field."
}

There are too many queries/reports currently processing. Please wait for others to finish.

Status: 429
{
  "code": 429,
  "message": "max concurrent queries per user (maximum_number_of_queries) reached"
}

Ejemplo 3: Obtenga actualizaciones de estado

Provea la capacidad para consultar/reportar el estado usando el guid proporcionado en el Ejemplo 2. Siga usando este API hasta que el informe muestre el estado “Completado”. Los estados posibles son:

 

  • Cancelado
  • Completado
  • Pendiente
  • Fallido
GET /_rest/v4/dwh/Q/{guid}/status
Status: 200

{

 "status": "Failed",

 "guid": "cb141a8039e146ad954ca70e5c0d08d6",

 "messages": [ "Query range to wide", "All data.fields have empty values, advise adding core fields" ]

}
Errores relacionados
Status: 500

[

  {

    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",

    "code": 500

  }

]
Ejemplo 4: Obtén el enlace de descarga de resultados

Una vez que el estado sea “Completado”, puede hacerse una solicitud para obtener la URL relativa para la descarga.

GET /_rest/v4/dwh/Q/{guid}
Status: 200

{

  "status": "Process finished. Download: [u'reports/guid1/guid2_QueryExport_1579194142011__000000000000.csv.gz']",

  "guid": "6ae69605c6e5ca352e664b0f96c8f84e"

}

Errores relacionados

Una vez que el estado sea “Completado”, puede hacerse una solicitud para obtener la URL relativa para la descarga.

 

Status: 500

[

  {

    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",

    "code": 500

  }

]

El ID solicitado no existe en la base de datos.

 

Status: 200

{

  "status": "Process has not finish yet, please verify the status of your request",

  "guid": "6ae69605c6e5ca352e664b0f96c8f84e"

}