Référence de l’API

Référence de l’API gRPC de KiloCenter — définitions Protocol Buffer pour les stations de base, les points de terminaison, avec portail en ligne.

KiloCenter fournit une API gRPC pour intégrer ou étendre la plateforme. Toutes les définitions d’API sont des Protocol Buffers hébergés dans le dépôt sous KC-Core/api/proto/.

Référence API interactive

Une référence API navigable avec tous les points de terminaison RPC est disponible à :

https://servicecenter-api.kiloiot.io/

Présentation de gRPC

gRPC est un framework RPC hautes performances qui utilise Protocol Buffers pour la sérialisation et HTTP/2 pour le transport. Pour plus d’informations, voir grpc.io.

L’API de KiloCenter est définie dans trois fichiers proto :

Fichier

Description

kilocenter.proto

Service unifié rétrocompatible (117 RPC au total)

core.proto

Messages du domaine central (points de terminaison, stations de base, messages, liaisons descendantes, événements, certificats, plans)

identity.proto

Messages du domaine d’identité (utilisateurs, organisations, clés API, authentification)

Génération de client

Go (avec buf — valeur par défaut du projet) :

cd KC-Core/api/proto && buf generate

Sortie : KC-Core/api/gen/ (uniquement des stubs Go — buf.gen.yaml configure les plugins Go).

Autres langages (avec protoc) :

# Exemple Python
python -m grpc_tools.protoc \\
  -I KC-Core/api/proto \\
  --python_out=./gen --grpc_python_out=./gen \\
  KC-Core/api/proto/kilocenter.proto \\
  KC-Core/api/proto/core.proto \\
  KC-Core/api/proto/identity.proto

buf.gen.yaml génère uniquement des stubs Go. Pour les autres langages, utilisez protoc ou ajoutez des plugins buf. Voir grpc.io/docs/languages pour des guides spécifiques à chaque langage.

Authentification

Édition communautaire

L’édition Community s’exécute avec l’authentification désactivée (KILOCENTER_AUTH_ENABLED=false). Aucun en-tête n’est requis pour aucun RPC — toutes les méthodes sont accessibles directement.

# Aucun en-tête d’authentification nécessaire
grpcurl -plaintext -d '{}' \\
  localhost:9090 kilocenter.api.v1.KiloCenterService/GetSystemStatus

Édition Entreprise

Lorsque l’authentification est activée (KILOCENTER_AUTH_ENABLED=true), trois en-têtes de métadonnées s’appliquent :

En-tête

Requis pour

Valeur

authorization

Tous les RPC non publics

Bearer <JWT_TOKEN> ou Bearer <API_KEY>

x-organization-id

Tous les RPC non exemptés

UUID de l’organisation cible

x-user-id

RPC appelés sans JWT (mode d’authentification par en-têtes uniquement)

UUID de l’utilisateur agissant

Méthodes publiques (aucun en-tête requis) : Connexion, RefreshTokens, GetAuthSettings, ExchangeOIDC, ExchangeOAuth2, GetReleaseInfo, RegisterAccount Source : KC-Core/pkg/grpc/public_methods.go

Méthodes exemptées d’organisation (authentification requise, aucun en-tête d’organisation) : GetSystemStatus, GetProfile, Déconnexion, ChangePassword, CRUD Utilisateur/Organisation/Adhésion (contexte d’organisation résolu à partir des champs de la requête) Source : KC-Core/pkg/grpc/public_methods.go → OrgExemptMethods

Les jetons d’API sont créés via KC-Web ou le CreateApiKey RPC.

Référence API par domaine

Points de terminaison (7)

CreateEndPoint, GetEndPoint, UpdateEndPoint, DeleteEndPoint, ListEndPoints, AttachEndPoint, DetachEndPoint

Stations de base (7)

CreateBaseStation, GetBaseStation, UpdateBaseStation, DeleteBaseStation, ListBaseStations, GetBaseStationStats, UpdateBaseStationEui

Messages (11)

GetMessage, ListMessages, StreamMessages, ListBaseStationMessages, GetBaseStationMessage, GetBaseStationMessageStats, SearchBaseStationMessages, ExportBaseStationMessages, StreamBaseStationMessages, ListEndpointMessages, ListBaseStationActivity

Liaisons descendantes (4)

SendDownlink, RevokeDownlink, ListDownlinkQueue, GetDownlinkResults

Transmission UL (1)

SendULTransmit

Contrôle des stations de base (2)

RequestBaseStationStatus, InitiatePing

Statut de réception DL (3)

GetDLRXStatus, QueryDLRXStatus, GetDLRXStatusQueries

Système (3)

GetSystemStatus, GetStatistics, GetReleaseInfo

Clés API (4)

CreateApiKey, GetApiKey, DeleteApiKey, ListApiKeys

Intégrations (5)

CreateIntegration, GetIntegration, UpdateIntegration, DeleteIntegration, ListIntegrations

Analytique (3)

GetAnalyticsOverview, GetActivityAnalytics, GetSignalQualityAnalytics

Événements et alertes (8)

ListEvents, ListBaseStationEvents, ListEndPointEvents, StreamEvents, StreamBaseStationEvents, StreamEndPointEvents, ListAlerts, GetAlertSummary

Surveillance SCACI (6)

ListScaciSessions, GetScaciSession, GetScaciStatistics, ListScaciErrors, ListScaciQueues, GetScaciStatus

Certificats (6)

GenerateCertificate, DownloadCertificate, DownloadBaseStationCertificate, GenerateServerCertificates, RenewServerCertificates, GetServerCertificateStatus

Fabricants (5)

CreateManufacturer, GetManufacturer, UpdateManufacturer, DeleteManufacturer, ListManufacturers

Modèles d’appareils (5)

CreateDeviceModel, GetDeviceModel, UpdateDeviceModel, DeleteDeviceModel, ListDeviceModels

Plans (8)

CreateBlueprint, GetBlueprint, UpdateBlueprint, DeleteBlueprint, ListBlueprints, SetDefaultBlueprint, SubmitBlueprintToRegistry, CreateDeviceModelWithBlueprint

Utilitaires de plans (1)

DecodePreview

Statistiques des points de terminaison (2)

GetEndPointStats, GetEndPointOperations

Auth et session (8) — Entreprise

Connexion, RefreshTokens, GetProfile, GetAuthSettings, Déconnexion, ChangePassword, ExchangeOIDC, ExchangeOAuth2

Inscription en libre-service (1) — Entreprise

RegisterAccount

Utilisateurs (6) — Entreprise

CreateUser, GetUser, UpdateUser, DeleteUser, ListUsers, UpdateUserPassword

Organisations (5) — Entreprise

CreateOrganization, GetOrganization, UpdateOrganization, DeleteOrganization, ListOrganizations

Adhésions aux organisations (6) — Entreprise

AddOrganizationUser, GetOrganizationUser, UpdateOrganizationUser, RemoveOrganizationUser, ListOrganizationUsers, ListUserOrganizations

RPC en streaming

Cinq RPC utilisent le streaming côté serveur pour fournir des données en temps réel :

RPC

Cas d’utilisation

StreamMessages

Messages de liaison montante en temps réel

StreamBaseStationMessages

Flux de messages de la station de base

StreamEvents

Notifications d’événements système

StreamBaseStationEvents

Flux d’événements de la station de base

StreamEndPointEvents

Flux d’événements du point de terminaison

const stream = client.streamMessages(request, metadata);
stream.on('data', (message) => { /* handle message */ });
stream.on('error', (err) => { /* handle error */ });
stream.on('end', () => { /* stream closed */ });

Pagination

Tous List* Les RPC prennent en charge la pagination basée sur un offset via page_size et page_token champs.

RPC de liste standard : 20 par défaut, 100 max Listes à fort volume (points de terminaison, stations de base, liaisons descendantes) : 100 par défaut, 1000 max

Source : KC-Core/pkg/grpc/pagination.go

message ListEndPointsRequest {
  int32 page_size = 1;    // 20 par défaut, 100 max
  string page_token = 2;  // Depuis ListEndPointsResponse.next_page_token précédent
}

Gestion des erreurs

Toutes les erreurs utilisent les codes d’état gRPC avec des jetons d’erreur lisibles par machine provenant de KC-Core/pkg/grpc/errors_catalog.go.

Code gRPC

Équiv. HTTP

Causes courantes

INVALID_ARGUMENT (3)

400

Requête mal formée, échecs de validation

NOT_FOUND (5)

404

La ressource n’existe pas

ALREADY_EXISTS (6)

409

Ressource en double

PERMISSION_DENIED (7)

403

Échec d’autorisation

UNAUTHENTICATED (16)

401

Jeton manquant ou invalide

FAILED_PRECONDITION (9)

400

Échec lié à l’état

INTERNAL (13)

500

Erreur serveur

Pour le modèle d’erreur complet et les plages de jetons d’erreur, voir docs/api.md.

Console API

La réflexion gRPC est activée sur KC-Gateway. Outils compatibles :

# grpcui — interface web interactive
grpcui -plaintext localhost:9090

# grpcurl — client en ligne de commande
grpcurl -plaintext localhost:9090 list

# Postman — utilisez l’onglet gRPC avec la réflexion serveur
# BloomRPC — client gRPC de bureau

Pour aller plus loin

Référence API complète — contrats requête/réponse et plages de jetons d’erreur
Fichiers sources Proto — définitions canoniques de l’API
Premiers pas avec gRPC — vérifier la connectivité et découvrir les méthodes

PrécédentDéveloppement assisté par LLM

SuivantExemples Go

Mis à jour il y a 3 mois