API de importación

El servicio de importación de Badger Meter Data Exchange (BDE) se basa en la interfaz de programación de aplicaciones (Application Programming Interface, API) de servicios comunes y procesa varios archivos de datos de BEACON a través de una interfaz de programación estándar. Data Exchange se utiliza para mantener la jerarquía de las cuentas y servicios de BEACON en sincronía con los datos de los clientes mediante la automatización del proceso de importación de datos. Además, el servicio de importación brinda soporte para ingresar las lecturas de los medidores en BEACON.


NOTA PARA LOS USUARIOS DE LA API DE BEACON EN CANADÁ

De acuerdo con las regulaciones canadienses sobre datos transfronterizos, sus datos de servicios públicos se trasladan o ya se trasladaron a Canadá. Como resultado, si inicia sesión en BEACON a través de beaconama.ca, deberá ajustar todas sus llamadas a la API para abordar las terminales en api.beaconama.ca.

Por ejemplo, cambie
https://api.beaconama.net/v1/eds/read/
a
https://api.beaconama.ca/v1/eds/read/

Este cambio afecta a todas las llamadas a la terminal de la API para las empresas de servicios públicos que inician sesión en beaconama.ca.


Resumen de la API

La API de importación de Data Exchange proporciona los siguientes métodos para admitir la funcionalidad del intercambio de datos.

/v1/bde/import

Método Descripción
POST Crear un nuevo Badger Meter Data Exchange.
PUT Aceptar la ejecución en seco de BEACON Data Exchange.

/v1/bde/import/{bdeUUID}

GETObtiene el estado de importación de un archivo de datos de BDE existente.

Método Descripción

/v1/bde/import/{bdeUUID}/report

Método Descripción
GET Obtiene el informe de un BDE que se completó correctamente.

Autenticación

La autenticación de acceso básico HTTP proporciona a sus aplicaciones el acceso seguro a todos los datos disponibles para su cuenta. Con su nombre de usuario y contraseña de BEACON, puede usar el método base64 de su biblioteca de programación para crear un encabezado de autorización HTTP. Para obtener una explicación de este procedimiento, consulte: http://en.wikipedia.org/wiki/Basic_access_authentication.

Badger Meter Data Exchange

POST /v1/bde/import

Cree un nuevo tipo de importación de BDE al enviar un archivo para un tipo particular de procesamiento. De forma predeterminada, esto iniciará una ejecución en seco de la ingestión de datos, la cual deberá aceptarse al emitir el método PUT correcto después de que se haya completado el procesamiento.

Carga de archivos como se describe en RFC 2388.

Nota: Los archivos deben ser de 30 MB o menos.

parámetro requerido tipo descripción
data (error) CSV El archivo CSV que se va a procesar.

Ejemplos:
Método POST de BDE::SolicitudPOST /v1/bde/import

curl

# Utilice este enunciado cURL a fin de crear un nuevo tipo de importación de BDE
# al enviar un archivo para un tipo particular de procesamiento.
# De forma predeterminada, se inicia una ejecución en seco que escanea el archivo
# en busca de errores. La importación debe aceptarse al emitir el
# método PUT correcto después de completar el procesamiento.
curl -uusername:password \ 
-F data=@filename.csv \
https://api.beaconama.net/v1/bde/import
#

Método POST de BDE::Respuesta

{
    "bdeUUID": "12313",
    "statusUrl": "/v1/bde/import/12313"
}

Respuesta

Da como respuesta el objeto BDENew.

202 Accepted: El BDE se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

    • el encabezado de ubicación dirige hacia statusUrl

 

POST /v1/bde/import?dryRun=false

Omitir la validación de prueba de un BDE.

Variables:

parámetro requerido datos descripción
dryRun booleano Falso para deshabilitar, verdadero para habilitar. El valor predeterminado es verdadero si no se proporciona.
data (error) CSV El archivo CSV que se va a procesar.

Ejemplos:

Método POST de BDE::Aceptar importación sin ejecución en seco

POST /v1/bde/import?dryRun=false

curl

# Utilice esta consulta cURL para deshabilitar el proceso de ejecución en seco
# y aceptar la importación de un archivo. El informe de excepciones seguirá
# estando disponible en la Lista de actividades de la página Assets>System Sync.
curl -v "https://api.beaconama.net/v1/bde/import?dryRun=false" \
-F "data=@file_name.csv;type=text/csv" \
-u"username:password"
#

Método POST de BDE::Respuesta

{
"bdeUUID": "12313",
"statusUrl": "/v1/bde/import/12313"
}

PUT /v1/bde/import/{bdeUUID}

Aceptar la ejecución en seco de un BDE.

Variables:

bdeUUID(error)UUIDEl identificador único universal (Universally Unique Identifier, UUID) de bdeType para aceptar la ejecución en seco.

parámetro requerido tipo descripción

Ejemplos:

Método PUT de BDE::Aceptar

PUT /v1/bde/import/12313

curl

# Utilice este enunciado cURL para aceptar una ejecución en seco de BDE.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313
#

Método POST de BDE::Respuesta

{
    "bdeUUID": "12313",
    "statusUrl": "/v1/bde/import/12313"
}

Respuesta
Da como respuesta el objeto BDENew.

202 Accepted: El BDE se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

  • el encabezado de ubicación dirige hacia statusUrl

GET /v1/bde/import/{bdeUUID}

Obtenga el estado de un BDE existente.

Variables:

bdeUUID(error)UUIDEl UUID de bdeType para obtener el estado del BDE.

parámetro requerido tipo descripción

Ejemplos:

Método GET de BDE estado::Solicitud

GET /v1/bde/import/12313

curl

# Use este enunciado cURL para obtener el estado
# de un archivo BDE existente.
curl -uusername:password \ 
-F data=@filename.csv \
https://api.beaconama.net/v1/bde/import
#

Método GET de BDE estado::Respuesta::En cola

{    
    "state": "queue",
    "dryRun": true,
    "message": "Provisioning Import operation queued for processing.",
    "queueTime": "2015-01-14T23:50:59Z"
}

Método GET de BDE estado::Respuesta::Ejecutando

{    
    "startTime": "2015-01-15T00:00:00Z",
    "dryRun": true,
    "state": "run",
    "progress": {
        "percentComplete": "12.0",
        "ETA": "2015-01-15T01:02:31Z",
        "message": "performing validation"
    },
    "message": "Import operation running.",
    "queueTime": "2015-01-14T23:50:59Z"
}

Método GET de BDE estado::Respuesta::Excepción

{
    "startTime": "2015-01-15T00:00:00Z",
    "dryRun": true,
    "state": "exception",
    "endTime": "2015-01-15T01:02:30Z",
    "message": "Import operation had problems.",
    "queueTime": "2015-01-14T23:50:59Z"
}

Método GET de BDE estado::Respuesta::Completado

{    
    "startTime": "2015-01-15T00:00:00Z",
    "dryRun": true,
    "state": "done",
    "endTime": "2015-01-15T01:02:30Z",
    "message": "Import operation succeeded.",
    "queueTime": "2015-01-14T23:50:59Z",
    "reportUrl": "/v1/bde/import/12313/report"
}

Respuesta

Da como respuesta el objeto BDEStatus.

GET /v1/bde/import/{bdeUUID}/report

Obtenga el informe generado después de que se haya procesado el BDE.

Variables:

bdeUUID(error)UUIDEl UUID de bdeType para obtener el informe.

parámetro requerido tipo descripción

Ejemplos:

Método GET de BDE informe::Solicitud

GET /v1/bde/import/12313/report

curl

# Use este enunciado cURL para obtener el informe que 
# se generó una vez que se procesó el BDE.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313/report
#

Método GET de BDE informe::Respuesta

{
    "dryRun": false,
    "ok": 104,
    "error": 23,
    "originalUrl": "/v1/content/import/12313/import.csv",
    "errorUrl": "/v1/content/import/12313/errors.json",
    "errorSheetUrl": "/v1/content/import/12313/errors.csv",
}
 

Respuesta

Da como respuesta el objeto BDEReport.

HCódigos de estado de HTTP

Código Descripción
200 OK Solicitud aceptada y debería incluir algo de contenido, asuma que la operación se completó.
202 Accepted Solicitud aceptada, pero el procesamiento no está completo. El encabezado de la ubicación dirigirá a una URL que mostrará el progreso o el resultado final.
400 Bad Request Solicitud con formato incorrecto.
401 Unauthorized No hay encabezado de autorización o no autorizado.
403 Forbidden El usuario no tiene permiso.
404 Not Found Esta respuesta se obtiene cuando se pasa un UUID de BDE para una búsqueda que no existe.
412 Precondition Failed Al solicitar un informe que aún no se ha generado.

Códigos de API

E-BDE-100 400 entidad Archivo no procesado.
E-BDE-200 400 disposición-de-contenido Falta el nombre de archivo.
E-BDE-201 400 disposición-de-contenido La longitud del nombre de archivo es demasiado larga, debe tener 255 caracteres como máximo.
E-BDE-300 409 estructura-de-archivo Se requiere al menos uno de los siguientes encabezados en el archivo: Account_ID, Meter_ID, Location_ID.
E-BDE-400 409 estructura-de-archivo El archivo solo contiene encabezados. Debe contener al menos una fila de datos para realizar la importación.

Objetos
Paginación
Los resultados de la paginación se muestran en un objeto contenedor de paginación, con los objetos reales bajo una propiedad de resultados.

total int El número total del conjunto.
from int El primer número de registro del conjunto en estos resultados. Iniciando en 1
to int El último número de registro del conjunto en estos resultados. Iniciando en 1
offset int Compensación de registro.
limit int Cuántos registros mostrar.
results Matriz de objetos Una matriz de los objetos de resultado. Consulte la API para conocer el tipo de objeto.

BDENew
Objeto creado en el momento de un nuevo BDE.

bdeType enum Tipo de BDE {input, read}
bdeUUID uuid UUID del BDE escrito.
statusUrl url URL para comprobar el estado de ejecución del BDE.

BDEResult

Objeto que devuelve información sobre un BDE.

bdeType enum Tipo de BDE {input, read}
bdeUUID uuid UUID del BDE escrito.
state enum Estado actual de un BDE {queue, run, exception, done}.
dryRun booleano Verdadero o falso dependiendo de si el bde fue una ejecución en seco o no.
importOk int Cuántos registros se validaron o importaron correctamente.
importError int Cuántos registros no se validaron o importaron correctamente.

BDEReport
Una vez completado el informe disponible para un BDE.

originalUrl url URL hacia el archivo que se cargó.
okCount int Número de registros que se procesaron correctamente.
errorCount int Número de registros que se procesaron incorrectamente.
errorUrl url URL hacia el archivo con registros que se procesaron incorrectamente.
errorSheetUrl url URL hacia el archivo codificado en CSV con registros que se procesaron incorrectamente.
dryRun booleano Verdadero o falso dependiendo de si la importación es una ejecución en seco.

BDEStatus

Llama a ese estado de respuesta de un BDE.

startTime fecha Fecha en que comenzó el procesamiento.
endTime fecha Fecha en que terminó el procesamiento.
queueTime fecha Fecha de la carga.
state enum Estado actual de un BDE {queue, run, exception, done}.
message cadena Mensaje en formato legible humano que describe el estado.
progress Progreso Progreso actual.
reportUrl URL Al finalizar el procesamiento: dónde encontrar información más detallada.
dryRun booleano Verdadero o falso dependiendo de si la importación es una ejecución en seco.

Progreso

Objeto que describe el progreso actual del trabajo en curso.

percentComplete float Progreso actual.
ETA fecha Fecha estimada de finalización.
message cadena Descripción del trabajo actual.

18 de octubre de 2017Se eliminaron los comandos GET /v1/bde/import CURL para mostrar todos los archivos anteriores y pendientes. Se eliminó el diagrama lógico de alto nivel.No se requiere ninguna acción.

Última actualización ¿Qué cambió? Lo que debe hacer
11 de febrero de 2016 Nuevo URL para acceder a nuestras terminales de API. Se añadieron códigos de error para la API. Actualice los URL en su código de acuerdo con la documentación.
Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.

A %d blogueros les gusta esto: