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

Méthode Description
POST Crée un nouveau Badger Meter Data Exchange.
PUT Accepte un essai de BEACON Data Exchange.

/v1/bde/import/{bdeUUID}

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

Méthode Description

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

Méthode Description
GET Obtient le rapport d’un BDE correctement effectué.

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 30 Mo.

param requis type description
data (erreur) 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 (erreur) 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 :

bdeUUID(erreur)UUIDLe bdeType UUID pour accepter l’essai.

param requis type description

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 :

bdeUUID(erreur)UUIDLe bdeType UUID pour obtenir l’état du BDE.

param requis type description

Exemples :

GET BDE status::Request

GET /v1/bde/import/12313

curl

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

GET BDE status::Response::Queued

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

GET BDE status::Response::Running

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

GET BDE status::Response::Exception

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

GET BDE status::Response::Complete

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

bdeUUID(erreur)UUIDLe bdeType UUID pour obtenir le rapport.

param requis type description

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

Code Description
200 OK Requête acceptée et il doit y avoir du contenu, considérez que l’opération est terminée.
202 Accepted Requête acceptée, mais le traitement n’est pas terminé. L’en-tête d’emplacement renvoie vers une URL qui indique la progression ou le résultat final.
400 Bad Request Requête mal formatée.
401 Unauthorized Aucun en-tête d’autorisation, ou pas autorisé.
403 Forbidden L’utilisateur ne dispose pas de la permission.
404 Not Found Renvoyé lors de l’utilisation d’un BDE UUID pour une consultation qui n’existe pas.
412 Precondition Failed Lorsqu’un rapport est demandé mais n’a pas encore été généré.

Codes d’API

E-BDE-100 400 entity Fichier non traité.
E-BDE-200 400 content-disposition Nom de fichier manquant.
E-BDE-201 400 content-disposition Nom de fichier trop long, doit comporter 255 caractères maximum.
E-BDE-300 409 file-structure Au moins l’un des en-têtes suivants est requis dans le fichier :
Account_ID, Meter_ID, Location_ID.
E-BDE-400 409 file-structure Le fichier contient uniquement des en-têtes – doit contenir au moins une rangée de données pour réaliser l’importation.

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.

total int Le nombre total dans la série.
from int Le premier numéro d’enregistrement de la série dans ces résultats. En commençant à 1
à int Le dernier numéro d’enregistrement de la série dans ces résultats. En commençant à 1
offset int Décalage d’enregistrement.
limit int Le nombre d’enregistrements à renvoyer.
résultats Object array (Tableau d’objets) Un tableau des objets de résultats – voir l’API pour le type d’objet.

BDENew

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

bdeType enum Type de BDE {input, read}
bdeUUID uuid UUID du BDE saisi.
statusUrl url URL pour vérifier l’état de l’exécution BDE.

BDEResult

Objet qui renvoie des informations concernant un BDE.

bdeType enum Type de BDE {input, read}
bdeUUID uuid UUID du BDE saisi.
état enum État actuel d’un BDE {queue, run, exception, done}
dryRun boolean (booléen) True ou false selon que le bde était ou non un essai.
importOk int Le nombre d’enregistrements correctement validés ou importés.
importError int Le nombre d’enregistrements qui n’ont pas été correctement validés ou importés.

BDEReport

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

originalUrl url URL vers le fichier qui a été téléchargé.
okCount int Nombre d’enregistrements traités correctement.
errorCount int Nombre d’enregistrements traités incorrectement.
errorUrl url URL vers le fichier avec les enregistrements qui ont été traités de manière incorrecte.
errorSheetUrl url URL vers le fichier CSV encodé avec les enregistrements qui ont été traités de manière incorrecte.
dryRun boolean (booléen) True ou false selon que l’importation était ou non un essai.

BDEStatus

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

startTime date Date à laquelle le traitement a commencé.
endTime date Date à laquelle le traitement s’est arrêté.
queueTime date Date de chargement.
state enum État actuel d’un BDE {queue, run, exception, done}
message string (chaîne) Message lisible par l’utilisateur décrivant l’état.
progress Progrès Progression actuelle.
reportUrl URL Lorsque le traitement est terminé – où trouver des informations plus détaillées.
dryRun boolean (booléen) true ou false selon que l’importation était ou non un essai.

Progrès

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

percentComplete float (flottant) Progression actuelle.
ETA date Date de fin estimée.
message string (chaîne) Description de la tâche actuelle.

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.

Dernière mise à jour Ce qui a changé Ce que vous devez effectuer
11 février 2016 Nouvelle URL pour accéder aux points de terminaison de notre API. Ajout de codes d’erreur de l’API. Mettez à jour les URL de votre code conformément à la documentation.
Knowledge Base

User Guide
Follow via Email

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

%d blogueurs aiment cette page :