Automatiser l'import de données avec CircleCI et Github

9 min - Author: Marine

Sommaire

Chez Woosmap, nous travaillons avec CircleCI, une solution d'intégration continue conçue pour aider les développeurs à « livrer un meilleur code, plus vite ». Ce tutoriel explique comment automatiser l'import de données dans la base Woosmap via CircleCI et Github. L'objectif n'est pas ici de faire de l'intégration ou du déploiement continu à proprement parler, mais de l'import et de la livraison continus de données à jour vers les utilisateurs finaux. Cette approche facilite la disponibilité des données en production.

Concepts de base

Intégration des données

Comme nous l'avons vu dans ce précédent article, l'une des premières étapes pour tirer parti de l'hébergement de vos données de magasins sur Woosmap est de consolider et transformer vos jeux de données de points de vente dans un format unifié compatible avec Woosmap. Beaucoup d'entre vous ont eu l'occasion d'intégrer des données via des outils ETL (Extract, Transform, Load) comme FME — une solution pertinente sans passer par du code. Une fois le workflow construit et exécuté, vos données sont en ligne. Encore faut-il les maintenir à jour : c'est tout l'objet de ce tutoriel.

Intégration continue

L'intégration continue (CI) est une pratique de développement qui consiste à fusionner régulièrement le code dans un dépôt partagé, plusieurs fois par jour. Chaque commit déclenche une compilation automatisée, ce qui permet aux équipes de détecter les problèmes tôt et de les corriger rapidement.

Déploiement continu

Le déploiement continu est étroitement lié à l'intégration continue : il désigne la mise en production automatique de tout code (ou de toute donnée) ayant passé les tests automatisés. En pratique, chaque build validé est déployé directement en production.

Workflow de l'exemple illustré

Le code source de l'exemple utilisé ici est disponible sur notre organisation Github Woosmap. L'objectif est de publier automatiquement et en toute sécurité de nouvelles données en production à destination des utilisateurs finaux. Pour cela, l'intégralité du processus de livraison continue doit être exécuté au préalable.

La première étape consiste à créer et pousser une version mise à jour de votre fichier de données (sur la branche develop dans notre cas, mais ce n'est pas obligatoire). Cela déclenche un build dans CircleCI, qui valide le JSON. Une fois le test passé, le fichier est envoyé sur un serveur de staging, puis, si l'import réussit, sur le serveur de production.

CircleCI

CircleCI est un service d'intégration continue hébergé qui prend en charge les tests automatisés, la compilation et le déploiement de vos applications. Il s'intègre à n'importe quel projet hébergé sur GitHub. Un hook est alors configuré pour notifier CircleCI à chaque push de nouveaux commits. Lorsque le hook se déclenche, CircleCI récupère le code source le plus récent, démarre une nouvelle VM pour le projet et exécute les tâches définies dans le fichier de configuration circle.yml à la racine du dépôt. Si l'une de ces tâches échoue, le build est marqué en rouge et annulé. Dans le cas contraire, il est marqué en vert et déployé dans l'environnement cible.

Créer un compte CircleCI

Pour démarrer avec CircleCI, connectez-vous via GitHub OAuth et « suivez » le dépôt que vous souhaitez utiliser. Dans votre navigateur, rendez-vous sur la page suivante : www.circleci.com. Cliquez sur le lien d'inscription. Vous serez redirigé vers la page SSO (authentification unique) de GitHub. Saisissez vos identifiants GitHub. GitHub vous demandera si CircleCI peut accéder à votre dépôt : vous devrez autoriser cet accès pour que CircleCI puisse suivre les modifications.

Adding your project

The project we want to automatically build on change is an open source repository hosted on our Woosmap Github Organization. After logging in to CircleCI, on the left-hand side menu, select the “Add Projects” option.

Organizations and Account

Choose an organization that you are a member of. You can also use your own GitHub account

Repository to Build

Choose a repo to add to CircleCI. It will start a new build for you each time someone pushes a new commit.

Lorsque vous sélectionnez le dépôt à compiler, CircleCI installe automatiquement les dépendances et lance le build. Par défaut, si aucun fichier de configuration circle.yml n'est trouvé, le build tente de localiser un dossier de tests, échoue et est marqué en rouge.

Configurer Circle.yml

Ce fichier définit les commandes à exécuter sur le serveur CI pour tester, compiler et déployer l'application et/ou les données. Placez-le à la racine de votre dépôt git : CircleCI le lit à chaque build (voir la documentation de configuration). Voici la configuration utilisée pour ce tutoriel :

# Specify which version of python to use
machine:
python:
version: 2.7.12
# A basic test to validate the JSON data file
test:
override:
- python -m json.tool 〈 data.json
# To specify any dependencies
dependencies:
override:
- pip install requests
# Triggered when we push to the master branch
deployment:
release:
branch: master
commands:
- >
WOOS_URL=$WOOS_PROD_URL
WOOS_PRIVATE_APIKEY=$WOOS_PROD_APIKEY
python import.py
# Triggered when we push to the develop branch
all:
branch: develop
commands:
- >
WOOS_URL=$WOOS_STAGING_URL
WOOS_PRIVATE_APIKEY=$WOOS_STAGING_APIKEY
python import.py

Cette configuration nous permet de contrôler :

Les variables d'environnement
La version de Python
Les commandes d'installation des dépendances
Les commandes pour exécuter les tests et les builds (si cette section ne contient aucune commande, vous devez fournir une commande factice comme /bin/true pour éviter que CircleCI ne signale l'absence de tests)
Les commandes de déploiement des données vers l'environnement cible (conditionnées par la branche Git sur laquelle le commit a été effectué)

Test

Pour cet exemple, nous n'avons pas besoin d'une suite de tests complexe : nous vérifions simplement que le fichier de données JSON en entrée est lisible et correctement formaté.

test:
override:
- python -m json.tool 〈 data.json

Environment Variables

To manage keys that must be kept secret, CircleCI offers to create Environment Variables inside the project build configuration (see official doc for more details). As you can see above, in the detailed workflow, the develop branch is linked to our Staging server and the master branch to the Production server. We added custom variables for the** APIKEY**, and** URL** relevant to the branch the commit was pushed to.

Pour accéder à la variable dans le script Python import.py, il suffit de référencer le nom de la propriété correspondante comme suit :

private_key = os.environ['WOOS_PRIVATE_APIKEY']
api_server_host = os.environ['WOOS_URL']

Script

Le script import.py, exécuté à la fin de chaque build, réalise un import simple vers l'environnement souhaité (staging ou production). Dans le fichier de configuration circle.yml, le script est lancé selon les lignes suivantes :

deployment:
release:
branch: master
commands:
- >
WOOS_URL=$WOOS_PROD_URL
WOOS_PRIVATE_APIKEY=$WOOS_PROD_APIKEY
python import.py

Voici le code résumé de ce qui est exécuté :

endpoint_json = 'data.json'
private_key = os.environ['WOOS_PRIVATE_APIKEY']
api_server_host = os.environ['WOOS_URL']
with open(endpoint_json, 'rb') as f:
data = json.loads(f.read())
session = requests.Session()
response = session.post('http://{api_server_host}/stores/replace'.format(
api_server_host=api_server_host),
params={'private_key': private_key},
json={'stores': data["stores"]})

Scheduled Build

Sometimes your data does not correspond to a flat JSON file but is returned by a web service that makes it really difficult to have a hook after changing data. You may need to configure a scheduled import triggered every X hours.

CircleCI is not designed for scheduled build. You can do so with competitors solutions like the well-known Travis-CI which have a Cron Jobs feature built-in. I would recommend using Travis-CI if you plan to do scheduled import but, as CircleCI offers an API, it’s also possible to run the build on demand and not only after a new commit.

Create a CircleCI API Token

Before using the API, you will need to create a Token attached to your account. Be careful that code and apps using this token can act as you, and have full read- and write-permission!

Navigate to CircleCI API Management and create a new Token.

Une fois votre token créé, vous pouvez utiliser l'API conformément à la documentation officielle. Par exemple, pour déclencher un build, envoyez une requête POST sur l'URL API suivante :

curl -X POST https://circleci.com/api/v1/project/woosmap/circleci-continuous-import/tree/master\?circle-token\=1234_fake_token_122343

Create a Scheduled Task using AWS Lambda Function

To trigger the API Call every X hours you need to set up a cron task. Amazon offers a simple way to do it using Lambda Function and CloudWatch Events. Follow this documentation to configure the trigger and the function. We added a sample lambda function inside the GitHub repo to help you deal with this feature. Here is what it looks like:

import json
import urllib2
def lambda_handler(event, context):
print("Received event: " + json.dumps(event, indent=2))
try:
request = urllib2.Request(
'https://circleci.com/api/v1/project/{project}/tree/{branch}?circle-token={circle_token}'.format(
project='woosmap/circleci-continuous-import',
branch='master',
circle_token='Fake_Token_a16I98h7b756b87dsgbb0f73c6b9fe435f1024'))
response = urllib2.urlopen(request)
return json.dumps(response.read(), indent=2)
except Exception as e:
print(e)
raise e

C'est tout. Vous pouvez tester votre fonction et ajuster la fréquence d'exécution. Dans CircleCI, vérifiez que votre build est bien déclenché et affiche un indicateur vert.

Conclusion

We’ve demonstrated just a simple “Hello World” example of continuous delivery of your data with CircleCI and GitHub. These tools are working pretty well together and the setup is really quick!

We have slightly hijacked a little the original use of CircleCI just to show how helpful this solution could be. In addition, all services used in this tutorial have a free plan: CircleCI, GitHub (for public and open source projects) and AWS Lambda/Cloudwatch.

If you have any questions about the content or the process described, please don’t hesitate to reach out to me through the contact page.

Useful Links

This script on the Woosmap Github Organization
CircleCI Documentation
Alternative to CircleCI : Travis-CI
Tutorial to set Amazon Lambda Function and CloudWatch Event