API d’importation

Le service d’importation Badger Meter Data Exchange (BDE) est basé sur l’API Common Services et traite différents fichiers de données BEACON via une interface de programmation standard. Data Exchange est utilisé pour maintenir la synchronisation de la hiérarchie des comptes et services avec les données des consommateurs en automatisant le processus d’importation des données. En outre, le service d’importation fournit un support pour saisir des relevés de compteurs dans BEACON.

REMARQUE POUR LES UTILISATEURS D’API BEACON AU CANADA

Les données de votre service sont en cours de transfert ou ont déjà été transférées au Canada conformément à la réglementation canadienne sur les données transfrontalières. Par conséquent, si vous vous connectez à BEACON via beaconama.ca, vous devez modifier tous vos appels d’API pour gérer des points de terminaison sur api.beaconama.ca.

Par exemple, remplacez
https://api.beaconama.net/v1/eds/read/
par
https://api.beaconama.ca/v1/eds/read/

Cette modification affecte l’ensemble des appels d’API de point de terminaison pour les services se connectant à beaconama.ca.

Présentation de l’API

L’API d’importation Data Exchange propose les méthodes suivantes pour prendre en charge la fonctionnalité d’échange de données.

/v1/bde/import

/v1/bde/import/{bdeUUID}

GETObtient l’état d’importation d’un fichier de données BDE existant.

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

Authentification

L’authentification d’accès de base HTTP offre à vos applications un accès sécurisé à toutes les données disponibles sur votre compte. À l’aide de votre nom d’utilisateur et de votre mot de passe BEACON, vous pouvez utiliser la méthode base64 de votre bibliothèque de programmation pour créer un en-tête HTTP Authorization. Pour consulter une explication de cette procédure, reportez-vous à : http://en.wikipedia.org/wiki/Basic_access_authentication.

Badger Meter Data Exchange

POST /v1/bde/import

Créez un nouveau BDE de type importation en soumettant un fichier pour un type de traitement particulier. Par défaut, cette action initie un essai de l’ingestion de données, qui devra être accepté en fournissant la méthode PUT correcte après la fin du traitement.

Chargement du fichier comme décrit dans RFC 2388 (document en anglais).

Remarque : les fichiers ne peuvent pas dépasser 70 Mo.

param	requis	type	description
data		CSV	Le fichier CSV à traiter.

Exemples :

POST BDE::Request

POST /v1/bde/import

curl

# Utilisez cette déclaration cURL pour créer un nouveau BDE de type importation#en soumettant un fichier pour un type de traitement particulier.
#Par défaut, un essai qui vérifie la présence d’erreurs dans le fichier est 
# initié. L’importation doit être acceptée en fournissant la
# méthode PUT correcte après la fin du traitement.
curl -uusername:password \ 
-F data=@filename.csv \
https://api.beaconama.net/v1/bde/import
#

POST BDE::Response

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

Response

Renvoie un objet BDENew.

202 Accepté – Le BDE a été soumis correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• • l’en-tête d’emplacement renvoie vers statusUrl

POST /v1/bde/import?dryRun=false

Passez la validation d’essai d’un BDE.

Variables :

param	requis	données	description
dryRun		boolean (booléen)	false pour désactiver, true pour activer. La valeur par défaut est true si elle n’est pas fournie.
data		CSV	Le fichier CSV à traiter.

Exemples :

POST BDE::Accept Import without Dry Run

POST /v1/bde/import?dryRun=false

curl

# Utilisez cette requête cURL pour désactiver le processus d’essai
# et accepter l’importation d’un fichier. Le rapport d’exceptions sera toujours 
# disponible dans la liste d’activités de la page Assets (Ressources) > System Sync (Synchronisation système).
curl -v "https://api.beaconama.net/v1/bde/import?dryRun=false" \
-F "data=@file_name.csv;type=text/csv" \
-u"username:password"
#

POST BDE::Response

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

PUT /v1/bde/import/{bdeUUID}

Acceptez l’essai d’un BDE.

Variables :

bdeUUIDUUIDLe bdeType UUID pour accepter l’essai.

Exemples :

PUT BDE::Accept

PUT /v1/bde/import/12313

curl

# Utilisez cette déclaration cURL pour accepter un essai BDE.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313
#

POST BDE::Response

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

Résponse

Renvoie un objet BDENew.

202 Accepté – Le BDE a été soumis correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• l’en-tête d’emplacement renvoie vers statusUrl

GET /v1/bde/import/{bdeUUID}

Obtenez l’état d’un BDE existant.

Variables :

bdeUUIDUUIDLe bdeType UUID pour obtenir l’état du BDE.

# Utilisez cette déclaration cURL pour obtenir l’état
# d’un fichier BDE existant.
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"
}

Résponse

Renvoie un objet BDENew.

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

Obtenez le rapport généré après que le BDE a été traité.

Variables :

bdeUUIDUUIDLe bdeType UUID pour obtenir le rapport.

Exemples :

GET BDE report::Request

GET /v1/bde/import/12313/report

curl

# Utilisez cette déclaration cURL pour obtenir le rapport qui 
# a été généré après le traitement du BDE.
curl -uusername:password \
https://api.beaconama.net/v1/bde/import/12313/report
#

GET BDE report::Response

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

Response

Renvoie un objet BDENew.

Codes d’état HTTP

Codes d’API

Objets

Pagination

Les résultats qui sont paginés sont renvoyés dans un objet wrapper de pagination, les objets réels étant dans une propriété de résultats.

BDENew

Objet créé au moment d’un nouveau BDE.

BDEResult

Objet qui renvoie des informations concernant un BDE.

BDEReport

Lorsqu’un rapport disponible pour un BDE est terminé.

BDEStatus

Appels qui renvoient l’état d’un BDE.

Progrès

Objet décrivant la progression actuelle de la tâche en cours.

18 octobre 2017Suppression des commandes GET /v1/bde/import CURL pour l’affichage de tous les fichiers précédents et en attente. Suppression du diagramme logique de haut niveau.Aucune action requise.