Exemples de scripts de service d’exportation de données

(Dernière mise à jour le 30 janvier 2019)
Vous trouverez ci-dessous des exemples de scripts PowerShell et Shell vous permettant d’automatiser rapidement le processus d’exportation de données de BEACON. Ils sont conçus pour vous montrer comment traiter les interactions avec les API EDS et ne comportent aucune gestion des erreurs.

Exemple PowerShell
ps_sample.ps1 appelle le point de terminaison de consommation EDS v1 pour obtenir un rapport sur la consommation totale ainsi que le nombre de compteurs indiquant un débit > 0 dans votre système.

Exemples Shell

Range.sh vous permet d’utiliser rapidement l’API de service d’exportation de données BEACON pour obtenir des lectures dans une plage de dates.

Flow.sh vous permet d’utiliser rapidement l’API de service d’exportation de données BEACON pour obtenir des données de consommation (débit) de vos compteurs.

Leak.sh vous permet d’utiliser rapidement l’API de service d’exportation de données BEACON pour obtenir une liste des compteurs présentant une fuite, la date de début de la fuite et le taux de fuite actuel.

Read.sh vous permet d’utiliser rapidement l’API de service d’exportation de données BEACON pour obtenir des données de lecture de facturation pour certains compteurs ou tous les compteurs de votre service.


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 DE L’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 DE L’API de point de terminaison pour les services se connectant à beaconama.ca.


Appels d’API avec PowerShell

PowerShell est un langage de script d’automatisation de tâche développé par Microsoft qui simplifie l’exécution d’appels à l’API REST et le traitement des données JSON et CSV. Powershell peut être exécuté sur Windows, MacOS et Linux.

Avant d’exécuter un script Powershell :

Windows

    • Téléchargez et installez la dernière version de PowerShell. (À l’heure actuelle, la dernière version est 6.2.4)
    • Ajoutez C:\Program Files\PowerShell\6.2.4-1.rhel.7.x86_64.rpm\LK à la variable d’environnement PATH.
    • Ouvrez l’invite de commandes et lancez PowerShell en saisissant pwsh.

MacOS

      • Téléchargez et installez le gestionnaire de paquets brew disponible à l’adresse https://brew.sh.
      • Une fois brew installé, saisissez brew cask install powershell dans une ligne de commande. Ceci permet d’installer PowerShell.

Pour plus d’informations sur l’utilisation de PowerShell, cliquez ici.


Utilisation de ps_sample.ps1 pour appeler le point de terminaison de consommation de l’API EDS v1

Copiez et collez le script ci-dessous dans un fichier et nommez-le ps_sample.ps1, par exemple. Ce script est exécuté depuis la ligne de commande et nécessite quatre paramètres : start_date (date de début), end_date (date de fin), username (nom d’utilisateur) et password (mot de passe).

  • Saisissez une date de début et, si vous le souhaitez, l’heure au format ISO sur la ligne 12 après $start_date=“AAAA-MM-JJ” ou $start_date=“AAAA-MM-JJThh:mm:ssZ”.
  • Saisissez une date de fin et, si vous le souhaitez, l’heure au format ISO sur la ligne 12 après $end_date=“AAAA-MM-JJ” ou $end_date=“AAAA-MM-JJThh:mm:ssZ”.
  • Renseignez les variables $username et $password avec vos informations d’identification d’utilisateur.
  • Saisissez l’unité de mesure souhaitée à la ligne 12.
  • Si vous le souhaitez, vous pouvez remplacer la variable resolution par quarter_hourly (tous les quarts d’heure), hourly (toutes les heures) ou monthly (tous les mois).
  • Lancez l’invite de commandes (Windows) ou saisissez pwsh dans Terminal (MacOS), puis appuyez sur la touche Entrée.
  • Exécutez ps_sample.ps1.
param (    
    [Parameter(Mandatory=$true)][string]$start_date,    
    [Parameter(Mandatory=$true)][string]$end_date,
    [Parameter(Mandatory=$true)][string]$username,
    [Parameter(Mandatory=$true)][string]$password
)
$encoded_creds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("$($username):$($password)"))
$basic_auth = "Basic $($encoded_creds)"

$uri = ’https://api.beaconama.net/v1/eds/consumption’
$headers = @{’Authorization’=$basic_auth;’Content-Type’=’application/x-www-form-urlencoded’}
$params = @{startDate=$start_date;endDate=$end_date;unit=’cubicmeter’;outputFormat=’CSV’;headerColumns=’Flow_Time,Flow’;resolution=’daily’}

$r = Invoke-RestMethod -Uri 
$uri -Headers $headers -Method POST -Body $params
$status_url = ’https://api.beaconama.net’+$r.statusUrl
While ($true) {    
    $r2 = Invoke-RestMethod -Uri $status_url -Headers $headers    
    Write-Output $r2
    if ($r2.state -eq ’done’) {
        $report_url = ’https://api.beaconama.net’ + $r2.reportUrl
        $out_file = "report.csv" 
        $result = Invoke-WebRequest -Uri $report_url -Headers $headers -MaximumRedirection 1 -ErrorAction SilentlyContinue -OutFile $out_file
        Break
    } else {
        Start-Sleep -Seconds 3
    }}
#
#
#

Pour exécuter le script nommé ps_sample.ps1 sur Windows, saisissez :

c:\ pwsh -ExecutionPolicy Bypass -File ps_sample.ps1 -start_date 2017-12-01 -end_date 2017-12-19 -username ZZZ -password YYY

Pour exécuter le script nommé ps_sample.ps1 sur MacOS, saisissez :

$ pwsh ./ps_sample.ps1 -start_date 2017-12-01 -end_date 2017-12-19 -username ZZZ -password YYY

Les scripts créeront un fichier CSV nommé report.csv. Une fois l’exécution du script terminée, vous pouvez passer en revue le contenu du fichier. Vous devriez obtenir quelque chose ressemblant à ceci :

"Flow_Time","Flow"                                                                                                                                                                                                                 "2017-12-01","6140.00000"                                                                                                                                                                                                           "2017-12-02","5652.40000"
"2017-12-03","5459.10000"
"2017-12-04","5289.20000"
"2017-12-05","5902.60000"
"2017-12-06","5426.50000"
"2017-12-07","5807.80000"

Dans PowerShell, fournissez les paramètres suivants si vous vous trouvez derrière un serveur mandataire : start_date (date de début), end_date (date de fin), votre nom d’utilisateur et votre mot de passe BEACON, ainsi que le nom d’utilisateur et le mot de passe de votre serveur mandataire Renseignez également les informations suivantes lorsque vous envoyez la requête réseau avec Invoke-RestMethod ou Invoke-WebRequest :

-Proxy ’<server:port>’ -ProxyUseDefaultCredentials ’<mot de passe du serveur mandataire>’

Consultez la ligne 19 de l’exemple de script ci-dessous.

Pour exécuter cette version de ps_sample.ps1 derrière un serveur mandataire sur Windows, saisissez :

c:\ pwsh -ExecutionPolicy Bypass -File ps_sample.ps1 -proxy ’<server:port>’ -start_date 2017-12-01 -end_date 2017-12-19 -username ZZZ -password YYY

Pour exécuter cette version de ps_sample.ps1 derrière un serveur mandataire sur MacOS, saisissez :

$ pwsh ./ps_sample.ps1 -proxy '<server:port>' -start_date 2017-12-01 -end_date 2017-12-19 -username ZZZ -password YYY
param (
    [Parameter(Mandatory=$true)][string]$start_date,
    [Parameter(Mandatory=$true)][string]$end_date,
    [Parameter(Mandatory=$true)][string]$username,
    [Parameter(Mandatory=$true)][string]$password,
    [Parameter(Mandatory=$true)][string]$proxy
)

$end_date = Get-Date -UFormat "%Y-%m-%d"
$end_date_for_file_name = Get-Date -UFormat "%Y%m%d-%H%m%S"
$out_file_name = "your-report-$($end_date)-report_$($end_date_for_file_name).csv"
$encoded_creds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("$($username):$($password)"))
$basic_auth = "Basic $($encoded_creds)"

$uri = 'https://api.beaconama.net/v1/eds/consumption'
$headers = @{'Authorization'=$basic_auth;'Content-Type'='application/x-www-form-urlencoded'}
$params = @{startDate=$start_date;endDate=$end_date;unit='cubicmeter';outputFormat='CSV';headerColumns='Flow_Time,Flow';resolution='daily'}

$r = Invoke-RestMethod -Uri $uri -Proxy $proxy -ProxyUseDefaultCredentials -Headers $headers -Method POST -Body $params
$headers = @{'Authorization'=$basic_auth;'Content-Type'='application/x-www-form-urlencoded'}
$status_url = 'https://api.beaconama.net'+$r.statusUrl

While ($true) {
    $r2 = Invoke-RestMethod -Uri $status_url -Proxy $proxy -ProxyUseDefaultCredentials -Headers $headers
    if ($r2.state -eq 'done') {
        $report_url = 'https://api.beaconama.net' + $r2.reportUrl
        $out_file = "report.csv"
        $result = Invoke-WebRequest -Uri $report_url -Proxy $proxy -ProxyUseDefaultCredentials -Headers $headers -MaximumRedirection 0 -ErrorAction SilentlyContinue
        if ($result.StatusCode -eq 302) {
            Invoke-WebRequest -Uri $result.Headers.Location -OutFile $out_file
            Write-Output "Report created in file: $($out_file)"
        }
        Break
    } else {
        Write-Output $r2.state
        Start-Sleep -Seconds 1
    }

Appels d’API avec des scripts ShellLes scripts Shell sont une autre manière d’envoyer des appels automatiques aux API de service Web. Exécutez ces exemples de script sur un système d’exploitation UNIX tel que Linux ou Mac OS X, ou utilisez Windows avec un ensemble d’outils à code source ouvert tel que Cygwin.

Assurez-vous d’exécuter CURL 6.58.0 ou une version ultérieure. Ceci permet de s’assurer que l’en-tête d’autorisation n’est pas transféré lors de la redirection pour extraire REPORT_URL.


CONSEIL : Lorsque vous transférez des paramètres d’exportation, comme Meter_ID=1234, que ce soit en tant que paramètres de requête ou dans le corps d’un HTTP POST, assurez-vous de les encoder par URL.


Avant d’exécuter l’un de ces scripts Shell :

Linux et MacOS :

    • Téléchargez et installez le gestionnaire de paquets brew disponible à l’adresse https://brew.sh.
    • Une fois brew installé, saisissez brew install jq dans une ligne de commande. Cela permet d’installer un processeur JSON appelé jq.

Windows

  • Consultez GitHub pour plus d’informations sur l’installation de jq sur Windows.

Utilisation de Range.sh

Utilisez cet appel d’API pour obtenir des lectures de compteur à intervalles pour une plage de dates.

  • Copiez et collez le script ci-dessous dans un fichier et nommez-le Range.sh.
  • Remplacez username:password à la ligne 2 par vos informations d’identification d’utilisateur BEACON en les séparant avec un signe deux-points (:). Assurez-vous d’inclure les guillemets (« ). Par exemple, CREDS= »votrenom:votremotdepasse ».
  • Saisissez une date de début et, si vous le souhaitez, l’heure au format ISO sur la ligne 4 après SDATE=« AAAA-MM-JJ » ou SDATE=« AAAA-MM-JJThh:mm:ssZ »
  • Saisissez une date de fin et, si vous le souhaitez, l’heure au format ISO sur la ligne 5 après EDATE=« YYYY-MM-JJ » ou EDATE=« AAAA-MM-JJThh:mm:ssZ »
  • Saisissez les valeurs de paramètre souhaitées à la ligne 9. Par exemple,
    • après resolution=, saisissez daily, hourly ou monthly
    • après unit=, saisissez acrefeet, ccf, cubicfeet, cubicmeter, gallons ou liter
  • Recherchez le script sur votre disque dur et saisissez ce qui suit dans un outil de ligne de commande :./Range.sh
  • Appuyez sur ENTRÉE pour exécuter le script. Une fois l’exécution du script terminée, copiez et collez les résultats dans un nouveau fichier. Enregistrez ce fichier et passez-le en revue dans une feuille de calcul ou une autre application capable de lire des fichiers CSV.
#!/bin/bash
CREDS='username:password'

SDATE='2017-07-31'
EDATE='2017-07-31'
COLS='Account_ID,Meter_ID,Endpoint_SN,Flow,Flow_Unit,Flow_Time'
URL='https://api.beaconama.net/v1/eds/range'

REQ=`curl -s -X POST -u$CREDS -d "resolution=daily&startDate=$SDATE&endDate=$EDATE&unit=cubicmeter&headerColumns=$COLS" $URL`
EDS_UUID=`echo $REQ | jq -r .edsUUID`

# Si le statut renvoie EDS_UUID, vérifie toutes les 10 secondes
# si le rapport est prêt. Une fois l’exportation terminée,# vous pouvez extraire le rapport de l’exportation. Notez que l’option curl -L est utilisée pour# permettre à curl de suivre automatiquement les redirections.

if [ ’$EDS_UUID’ != ’null’ ]then  while true  do      sleep 10 # Vérifie le statut toutes les 10 secondes.
      REQ=`curl -s -X GET -u$CREDS https://api.beaconama.net/v1/eds/status/$EDS_UUID`      echo REQ=$REQ      REPORT_URL=`echo $REQ | jq -r .reportUrl`            if [[ $REPORT_URL != 'null' ]]
      then
          
          curl -L -s -X GET -u$CREDS https://api.beaconama.net/$REPORT_URL -o $OUTFILE
          
          break
      fi
  done
else
  echo 'ERROR: $REQ'
fi
#
#
#

Utilisation de Flow.sh
Avant d’exécuter le script :

    • Copiez et collez le script ci-dessous dans un fichier et nommez-le Flow.sh.
    • Remplacez username:password à la ligne 2 par vos informations d’identification d’utilisateur BEACON en les séparant avec un signe deux-points (:). Assurez-vous d’inclure les guillemets. Par exemple, CREDS= »votrenom:votremotdepasse ».
    • Saisissez une date de début et, si vous le souhaitez, l’heure au format ISO sur la ligne 4 après SDATE=« AAAA-MM-JJ » ou SDATE= »AAAA-MM-JJThh:mm:ssZ »
    • Saisissez une date de fin et, si vous le souhaitez, l’heure au format ISO sur la ligne 5 après EDATE=« YYYY-MM-JJ » ou EDATE=« AAAA-MM-JJThh:mm:ssZ »
    • Saisissez les valeurs de paramètre souhaitées à la ligne 9. Par exemple,
      • après resolution=, saisissez daily, hourly ou monthly
      • après unit=, saisissez acrefeet, ccf, cubicfeet, cubicmeter, gallons ou liter
    • Enregistrez le fichier et nommez-le Flow.sh.
    • Recherchez le script sur votre disque dur, dirigez-y votre outil de ligne de commande et saisissez ce qui suit dans la ligne de commande :./Flow.sh
    • Appuyez sur ENTRÉE pour exécuter le script. Une fois l’exécution du script terminée, copiez et collez les résultats dans un nouveau fichier. Enregistrez ce fichier et passez-le en revue dans une feuille de calcul ou une autre application capable de lire des fichiers CSV.
#!/bin/bash
CREDS="username:password"

SDATE="2017-07-31"
EDATE="2017-07-31"
COLS="Account_ID,Meter_ID,Endpoint_SN,Flow,Flow_Unit,Point_1_Read,Point_1_Read_Time,Point_2_Read,Point_2_Read_Time"
URL="https://api.beaconama.net/v1/eds/flow"

REQ=`curl -s -X POST -u$CREDS -d "resolution=daily&startDate=$SDATE&endDate=$EDATE&unit=cubicmeter&headerColumns=$COLS" $URL`
EDS_UUID=`echo $REQ | jq -r .edsUUID`

# Si le statut renvoie EDS_UUID, vérifie toutes les 10 secondes
# si le rapport est prêt. Une fois l’exportation terminée,# vous pouvez extraire le rapport de l’exportation. Notez que l’option curl -L est utilisée pour# permettre à curl de suivre automatiquement les redirections.

if [ ’$EDS_UUID’ != ’null’ ]then  while true  do      sleep 10 # Vérifie le statut toutes les 10 secondes.
      REQ=`curl -s -X GET -u$CREDS https://api.beaconama.net/v1/eds/status/$EDS_UUID`      echo REQ=$REQ      REPORT_URL=`echo $REQ | jq -r .reportUrl`            if [[ $REPORT_URL != 'null' ]]
      then
          
          curl -L -s -X GET -u$CREDS https://api.beaconama.net/$REPORT_URL -o $OUTFILE
          
          break
      fi
  done
else
  echo 'ERROR: $REQ'
fi
#
#
#

Utilisation de Leak.sh

Utilisez cet exemple de script pour appeler le point de terminaison /v2/eds/leak et récupérer une liste des compteurs présentant une fuite, ainsi que la date de début de la fuite et le taux de fuite actuel.

  • Copiez et collez le texte ci-dessous dans un fichier texte et nommez-le Leak.sh.
  • Remplacez « username:password » par vos informations d’identification d’utilisateur BEACON.
  • Enregistrez le fichier.
  • Recherchez le script sur votre disque dur, dirigez-y votre outil de ligne de commande et saisissez ce qui suit dans la ligne de commande :./Leak.sh
  • Appuyez sur ENTRÉE pour exécuter le script. Une fois l’exécution du script terminée, copiez et collez les résultats dans un nouveau fichier. Enregistrez ce fichier et passez-le en revue dans une feuille de calcul ou une autre application capable de lire des fichiers CSV.
  • #!/bin/bash
    CREDS='username:password'
    
    COLS='Account_ID,Meter_ID,Current_Leak_Rate,Current_Leak_Start_Date'
    URL='https://api.beaconama.net/v2/eds/leak'
    
    REQ=`curl -s -X POST -u$CREDS -d 'Header_Columns=$COLS' $URL`
    EDS_UUID=`echo $REQ | jq -r .edsUUID`
    
    # # Si le statut renvoie EDS_UUID, vérifie toutes les 10 secondes
    # si le rapport est prêt. Une fois l’exportation terminée,# vous pouvez extraire le rapport de l’exportation. Notez que l’option curl -L est utilisée pour# permettre à curl de suivre automatiquement les redirections.
    
    if [ ’$EDS_UUID’ != ’null’ ]then  while true  do      sleep 10 # Vérifie le statut toutes les 10 secondes.
          REQ=`curl -s -X GET -u$CREDS https://api.beaconama.net/v1/eds/status/$EDS_UUID`      echo REQ=$REQ      REPORT_URL=`echo $REQ | jq -r .reportUrl`            if [[ $REPORT_URL != ’null’ ]]      then                    curl -L -s -X GET -u$CREDS https://api.beaconama.net/$REPORT_URL -o $OUTFILE                    break      fi  doneelse  echo ’ERROR: $REQ’fi###

    Utilisation de Read.sh
    Utilisez ce script d’exemple pour obtenir des données de lecture de facturation pour certains compteurs ou tous les compteurs de votre service.

  • Copiez et collez ce script dans un fichier et nommez-le Read.sh.
  • Remplacez username:password à la ligne 2 par vos informations d’identification d’utilisateur BEACON en les séparant avec un signe deux-points (:). Assurez-vous d’inclure les guillemets. Par exemple, CREDS=’votrenom:votremotdepasse’.
  • Saisissez une date de début et, si vous le souhaitez, l’heure au format ISO sur la ligne 4 après SDATE=’AAAA-MM-JJ’ ou SDATE=’AAAA-MM-JJThh:mm:ssZ’
  • Remplacez les exemples de valeur Meter_ID à la ligne 6 par des valeurs Meter_ID réelles pour autant de compteurs que vous le souhaitez. Utilisez des esperluettes (&) pour séparer chaque Meter_ID.Supprimez la ligne 6 de ce script pour récupérer des lectures pour tous les compteurs de votre service.
  • Enregistrez le fichier et nommez-le Read.sh.
  • Recherchez le script sur votre disque dur, dirigez-y votre outil de ligne de commande et saisissez ce qui suit dans la ligne de commande :./Read.sh
  • Appuyez sur ENTRÉE pour exécuter le script. Une fois l’exécution du script terminée, copiez et collez les résultats dans un nouveau fichier. Enregistrez ce fichier et passez-le en revue dans une feuille de calcul ou une autre application capable de lire des fichiers CSV.
#!/bin/bashCREDS=’username:password’DATE=’2019-11-07T00:00:00Z’URL=’https://api.beaconama.net/v2/eds/read’COLUMNS=’Location_ID,Service_Point_ID,Meter_ID,Meter_SN,Register_Number,Endpoint_SN,Billing_Read,Read_Unit,Read_Time’METERS=’Meter_ID=11111111&Meter_ID=22222222&Meter_ID=33333333&Meter_ID=44444444’# ---------------------------------------------------------------------------------------REQ=`curl -s -u$CREDS -H "Content-Type: application/x-www-form-urlencoded" -d "Date=${DATE}&${METERS}&Header_Columns=${COLUMNS}" -X POST $URL`# echo ${REQ}EDS_UUID=`echo $REQ | jq -r .edsUUID`# Si le statut renvoie EDS_UUID, vérifie toutes les 10 secondes# si le rapport est prêt. Une fois l’exportation terminée,# vous pouvez extraire le rapport de l’exportation. Notez que l’option curl -L est utilisée pour# permettre à curl de suivre automatiquement les redirections.
if [ ’$EDS_UUID’ != ’null’ ]then  while true  do      sleep 10 # Vérifie le statut toutes les 10 secondes.
      REQ=`curl -s -X GET -u$CREDS https://api.beaconama.net/v1/eds/status/$EDS_UUID`      echo REQ=$REQ      REPORT_URL=`echo $REQ | jq -r .reportUrl`            if [[ $REPORT_URL != 'null' ]]
      then
          curl -L -s -X GET -u$CREDS https://api.beaconama.net/$REPORT_URL [-0] $OUTFILE
          break
      fi
  done
else
  echo 'ERROR: $REQ'
fi
#
#
#
Knowledge Base

User Guide
Follow via Email

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

%d blogueurs aiment cette page :