Centiloc Service Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Geocore
  2. /
  3. API

API

Les APIs Geocore sont des APIs gRPC.

Dans la section Download, vous pouvez trouver les archives de :

  • API packages (fichiers tgz api-core) incluant les packages npm, pypi, nuget, maven, pubdev, ainsi que les fichiers proto pour chaque service d’API
  • MQTT data models (fichiers tgz mqtt-transtream)

Vous y trouverez également un outil de simulation vous aidant à exploiter l’API evttest pour générer de faux évènements sur vos cartes à des fins de test.

Veuillez contacter l’équipe support pour obtenir des identifiants d’accès à la zone de téléchargement.

Pour des raisons de gestion de ressources, seule l’API Geo est déployée par défaut.

Evttest et Perso sont déployées dans votre environnement à la demande. Veuillez contacter l’équipe support.

Charger les packages

Charger un package à partir d’un fichier local peut être une nouveauté pour vous, même si vous utilisez ces gestionnaires de packages depuis des années. Dans notre cas, les packages ne sont pas hébergés sur des registres publics comme PyPI, NuGet.org, npmjs.com ou pub.dev.

À la place, nous fournissons des archives (tarballs, nupkg, jars, …) que vous pouvez :

  • installer directement dans votre environnement local, et/ou
  • re-publier dans vos propres registres privés.

Ci-dessous, vous trouverez des guides pour charger un package dans votre environnement local.

pip est le gestionnaire de packages standard pour le langage de programmation python.

Les modules d’API sont fournis au format tar.gz. Par exemple :

  • pypi-centiloc_core-1.15.2.tar.gz

Copiez ce fichier dans votre projet (par exemple dans un répertoire vendor/), puis installez-le dans votre environnement Python (virtuel) :

Vous devez avoir pip installé.

Depuis le répertoire où se trouve le fichier :

python -m pip install --upgrade pypi-centiloc_core-1.15.2.tar.gz
# ou, plus généralement :
python -m pip install --upgrade ./pypi-centiloc_core-<VERSION>.tar.gz

Une fois installé, vous pouvez importer et utiliser les modules générés :

from centiloc_core.geo import board_pb2_grpc
from centiloc_core.geo import common_pb2

# […]
board_arg = common_pb2.BoardID(sn=board_sn)

Vous pouvez également pousser ce même tar.gz vers votre propre registre compatible PyPI (Artifactory, Nexus, …) si vous le souhaitez.

nuget est un format de package pour la technologie .NET, comme C# ou Visual Basic.

Les modules d’API sont fournis au format .nupkg. Par exemple :

  • Centiloc.Core.1.15.2.nupkg

Nous recommandons d’utiliser un répertoire local comme source, en complément de vos sources NuGet habituelles (par exemple nuget.org ou un feed privé).

  1. Copiez le fichier dans un répertoire local :
mkdir -p ./packages
cp Centiloc.Core.1.15.2.nupkg ./packages/
  1. Créez un fichier NuGet.config à côté de votre .csproj pour déclarer la source locale :
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="centiloc-local" value="./packages" />
  </packageSources>
</configuration>
  1. Ajoutez le package à votre projet :
dotnet add package Centiloc.Core --version 1.15.2

Centiloc.Core sera résolu depuis ./packages. Les autres dépendances seront résolues via vos sources NuGet déjà configurées sur la machine (par exemple nuget.org ou un feed interne).

Puis restaurez et compilez comme d’habitude :

dotnet restore
dotnet build

Si vous disposez déjà d’un feed NuGet privé, vous pouvez aussi y uploader Centiloc.Core.1.15.2.nupkg et le consommer comme un package standard à partir de votre propre source.

npm est le gestionnaire de packages pour l’écosystème Node.js et JavaScript/TypeScript.

Les modules d’API sont fournis sous forme d’archives tgz produites par npm pack. Par exemple :

  • npm-centiloc-centiloc_core-1.15.2.tgz

Ce fichier contient un package.json et les stubs JS/TS générés.

Option 1 – Installer directement depuis le tarball

Copiez le fichier dans votre projet (par exemple dans un répertoire vendor/) :

cp /download/path/npm-centiloc-centiloc_core-1.15.2.tgz ./vendor/

Puis, depuis la racine de votre projet :

npm install ./vendor/npm-centiloc-centiloc_core-1.15.2.tgz
# ou avec pnpm/yarn si vous préférez

Cela ajoutera le package dans votre node_modules et dans votre package-lock.json.

Option 2 – Le déclarer comme dépendance fichier dans package.json

Au lieu d’appeler npm install directement, vous pouvez déclarer le tarball comme dépendance :

{
  "dependencies": {
    "@centiloc/centiloc_core": "file:./vendor/npm-centiloc-centiloc_core-1.15.2.tgz"
  }
}

(adaptez le nom du package à ce qui est défini dans le champ name du package.json inclus dans le tarball.)

Puis lancez :

npm install

Vous pouvez ensuite importer les stubs générés dans votre code, par exemple :

// Exemple – le chemin réel dépend de la structure du package
import { GeoClient } from '@centiloc/centiloc_core/geo';

Vous pouvez également pousser ce tarball vers votre propre registre compatible npm si vous en avez un.

Pour les projets Java / Kotlin, nous fournissons :

  • maven-centiloc-core-1.15.2.jar
  • maven-centiloc-core-1.15.2.pom (POM nettoyé avec les dépendances, sans URL internes Centiloc)

Ces fichiers représentent un artefact Maven standard :

<groupId>com.centiloc</groupId>
<artifactId>centiloc-core</artifactId>
<version>1.15.2</version>

Option 1 – Installer dans votre dépôt Maven local

Depuis le répertoire contenant le JAR et le POM :

mvn install:install-file \
  -Dfile=maven-centiloc-core-1.15.2.jar \
  -DpomFile=maven-centiloc-core-1.15.2.pom

Cela installe l’artefact dans votre dépôt local ~/.m2/repository. Vous pouvez ensuite le référencer depuis un autre projet Maven :

<dependencies>
  <dependency>
    <groupId>com.centiloc</groupId>
    <artifactId>centiloc-core</artifactId>
    <version>1.15.2</version>
  </dependency>
</dependencies>

Ensuite, un simple :

mvn clean install

résoudra l’API Centiloc et toutes ses dépendances transitives (Protobuf, gRPC, etc.).

Option 2 – Re-publier dans votre propre dépôt Maven

Si vous disposez d’un dépôt Maven privé (Nexus, Artifactory, GitLab Package Registry, …), vous pouvez utiliser :

mvn deploy:deploy-file \
  -Dfile=maven-centiloc-core-1.15.2.jar \
  -DpomFile=maven-centiloc-core-1.15.2.pom \
  -DrepositoryId=<your-repo-id> \
  -Durl=<your-repo-url>

Une fois publié, vos projets peuvent consommer com.centiloc:centiloc-core:1.15.2 directement depuis votre registre.

Pour Dart / Flutter, nous fournissons une structure de package prête à l’emploi sous forme de tarball :

  • dart-centiloc_core_dart_v1.15.2.tgz

Dans cette archive, vous trouverez :

  • un pubspec.yaml
  • un dossier lib/ avec les stubs .dart générés

1. Extraire le package

Choisissez un répertoire où vous stockez le code tiers, par exemple third_party/centiloc_core :

mkdir -p third_party/centiloc_core
tar -C third_party/centiloc_core -xvzf dart-centiloc_core_dart_v1.15.2.tgz

Après extraction, third_party/centiloc_core/ doit contenir un pubspec.yaml et lib/.

2. Le référencer via une dépendance path

Dans le pubspec.yaml de votre application :

dependencies:
  centiloc_core:
    path: ../third_party/centiloc_core

(adaptez le chemin en fonction de votre organisation de projet.)

Puis lancez :

dart pub get
# ou :
flutter pub get

Vous pouvez maintenant importer les APIs générées dans votre code Dart / Flutter :

import 'package:centiloc_core/geo/geo.pbgrpc.dart';

Remarque : il s’agit d’une dépendance path – le package n’est pas publié sur pub.dev. Vous êtes libre de le ré-héberger sur votre propre serveur si vous disposez d’un serveur pub privé.

Pour Go, nous fournissons actuellement un tarball contenant les fichiers .pb.go générés, mais pas de fichier go.mod :

  • proto-centiloc__proto.v1.15.2.tgz

Ce tarball contient des packages Go générés à partir des définitions Protobuf (par exemple geo, perso, etc.). Il est destiné à être vendored directement dans votre application.

Il y a deux manières principales de le consommer, selon la façon dont vous gérez vos modules Go.

Option 1 – Style GOPATH (simple, old-school)

  1. Inspectez un des fichiers générés (par exemple geo.pb.go) et retrouvez son chemin d’import, dérivé de option go_package dans le fichier .proto, par exemple :

    package geo

// commentaire de chemin d’import, par exemple :
// option go_package = "git.centiloc.com/centiloc/core/geo;geo";

  2. Extrayez le tarball dans votre $GOPATH/src de sorte que le répertoire corresponde à ce chemin :

    # exemple avec go_package = "git.centiloc.com/centiloc/core/geo;geo"
mkdir -p "$GOPATH/src/git.centiloc.com/centiloc/core"
tar -C "$GOPATH/src/git.centiloc.com/centiloc/core" -xvzf proto-centiloc__proto.v1.15.2.tgz

  3. Dans votre code Go, importez le package avec ce chemin :

    import "git.centiloc.com/centiloc/core/geo"

func useAPI() {
    var id geo.BoardID
    _ = id
}

Go compilera en utilisant les sources que vous avez décompressées sous $GOPATH.

Option 2 – Modules Go avec replace (recommandé si vous utilisez des modules)

Si votre projet utilise les modules Go (go.mod), vous pouvez :

  1. Extraire le tarball dans un dossier à l’intérieur de votre repo, par exemple :

    mkdir -p internal/vendor/centiloc_proto
tar -C internal/vendor/centiloc_proto -xvzf proto-centiloc__proto.v1.15.2.tgz

  2. Dans votre go.mod, ajoutez une directive replace qui fait correspondre le chemin d’import issu de go_package à ce dossier local. Par exemple, si go_package est :

    option go_package = "git.centiloc.com/centiloc/core/geo;geo";

    alors dans go.mod :

    module your.app/module

go 1.21

require git.centiloc.com/centiloc/core v1.15.2

replace git.centiloc.com/centiloc/core => ./internal/vendor/centiloc_proto

  3. Votre code peut alors importer en utilisant le chemin canonique :

    import "git.centiloc.com/centiloc/core/geo"

Important : adaptez toujours les chemins d’import / la cible du replace au go_package réellement utilisé dans les fichiers Protobuf pour votre version d’API.

gdoc_arrow_left_alt Match Labels Core.Geo gdoc_arrow_right_alt