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

/v1/bde/import/{bdeUUID}

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

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

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 70 MB o menos.

parámetro	requerido	tipo	descripción
data		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		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:

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

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:

bdeUUIDUUIDEl UUID de bdeType para obtener el estado del BDE.

# 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
#

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

{    
    "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"
}

{
    "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"
}

{    
    "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:

bdeUUIDUUIDEl UUID de bdeType para obtener el informe.

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ódigos de API

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.

BDENew
Objeto creado en el momento de un nuevo BDE.

BDEResult

Objeto que devuelve información sobre un BDE.

BDEReport
Una vez completado el informe disponible para un BDE.

BDEStatus

Llama a ese estado de respuesta de un BDE.

Progreso

Objeto que describe el progreso actual del trabajo en curso.

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.