Menu de la documentation
Référence du SDK
Identifiants par type de stockage, clés d’emplacement, erreurs et appels HTTP directs.
En bref
Cette page liste ce que le SDK envoie pour chaque type de ressource : identifiants de stockage, emplacements des datasets et des collections. Elle décrit aussi les réponses d'erreur, et comment appeler l'API de la plateforme sans le SDK. Pour les notions, commencez par SDK Python.
Identifiants par type de stockage
client.storage_systems.create(…, kind=…, credentials={…}) attend ces champs. Les identifiants sont chiffrés avant d'être enregistrés et ne sont jamais renvoyés.
| Type | Obligatoires | Facultatifs |
|---|---|---|
POSTGRESQL | host, user, password, database | port (5432 par défaut) |
MYSQL | host, user, password, database | port (3306 par défaut) |
CLICKHOUSE | host, user, database | password, port, secure, interface (http ou native) |
SNOWFLAKE | account, user, database, et password ou private_key | warehouse, role, schema |
REDSHIFT | host, user, password, database | port (5439 par défaut), ssl (true par défaut) |
DATABRICKS | server_hostname, http_path, access_token | catalog, schema |
BIGQUERY | client_email, private_key, project_id | les autres champs du fichier de compte de service |
FABRIC | server, database, tenant_id, client_id, client_secret | — |
S3 | access_key_id, secret_access_key | region (us-east-1 par défaut), endpoint_url, bucket, session_token |
GOOGLE_DRIVE | client_email, private_key | les autres champs du fichier de compte de service |
ONEDRIVE | tenant_id, client_id, client_secret | — |
SHAREPOINT | tenant_id, client_id, client_secret, et site_id ou site_url | — |
Pour les comptes de service Google, lisez le fichier JSON dans votre code et envoyez ses champs. Un fichier entier passé comme une seule valeur (service_account ou service_account_json) est refusé.
Un champ obligatoire manquant échoue avec une réponse 400 qui nomme les champs manquants.
Emplacements des datasets
location indique où se trouve la table ou le fichier. Ses clés dépendent du type du système de stockage :
| Type | Clés de location |
|---|---|
POSTGRESQL, MYSQL, REDSHIFT, FABRIC | schema, table |
CLICKHOUSE | database, table |
SNOWFLAKE | database, schema, table |
DATABRICKS | catalog, schema, table |
BIGQUERY | project, dataset, table |
S3 | bucket, key, et éventuellement format : csv, tsv ou parquet |
GOOGLE_DRIVE | folderId, fileId |
ONEDRIVE | driveId, folderId, fileId |
SHAREPOINT | siteId, driveId, folderId, fileId |
Sur Microsoft Fabric, ajoutez database pour une table située hors de la base de la connexion.
Le système de stockage et l'emplacement identifient un dataset : un upsert avec le même couple met à jour le dataset existant. type vaut TABLE, VIEW ou MATERIALIZED_VIEW.
Emplacements des collections
| Type | Clés de location |
|---|---|
GOOGLE_DRIVE | folderId (folder_id est accepté). Pour un drive partagé, ajoutez driveId. |
S3 | bucket, prefix |
ONEDRIVE | driveId, folderId |
SHAREPOINT | siteId, driveId, folderId |
Une collection est identifiée par son slug, et par son système de stockage et son emplacement. create échoue avec 409 si l'un des deux existe déjà. upsert met à jour la collection correspondante, et échoue avec 409 si le slug et l'emplacement désignent deux collections différentes.
Réponses d'erreur
| Statut | Signification | Corps |
|---|---|---|
400 | Entrée invalide | {"error": "invalid_input", "message": "…"} |
401 | Clé absente, inconnue ou révoquée | {"error": "Unauthorized"} |
403 | Le compte n'a pas la fonctionnalité ou le droit sur la ressource | {"error": "Forbidden"} |
404 | La ressource n'existe pas, ou le compte ne peut pas la voir | {"error": "…"} |
409 | create sur une clé métier qui existe déjà | {"error": "conflict", "message": "…", "detail": {"existing_id": "…", "conflict_key": "slug"}} |
Le SDK lève PermissionError sur 401 et httpx.HTTPStatusError sur les autres ; error.response.json() donne le corps.
Appels HTTP directs
Le SDK est le moyen d'intégration pris en charge. Si vous ne pouvez pas utiliser Python, appelez la même API : l'adresse de base est votre NORTHSTAR_API_URL, et chaque requête porte la clé.
curl -H "X-API-KEY: $NORTHSTAR_API_KEY" "$NORTHSTAR_API_URL/me"GET /me renvoie le compte et son organisation : utilisez-le pour vérifier une clé. Les principaux appels d'écriture, relatifs à l'adresse de base :
| Appel | Méthode et chemin |
|---|---|
| Système de stockage | POST /feature/data-storage-systems/create ou /upsert |
| Dataset | POST /feature/datasets/create ou /upsert |
| Analyse d'un dataset | POST /feature/datasets/{id}/analysis/run |
| Collection de documents | POST /feature/document-collections/create ou /upsert, puis /ingest |
| Source | POST /feature/data-sources/create ou /upsert |
| KPI | POST /feature/kpi-catalogue |
| Tableau de bord | POST /feature/dashboards |
Les corps reprennent les noms d'arguments du SDK en snake_case, plus organization_id, que le SDK lit dans GET /me. Les corps des KPIs et des tableaux de bord sont en camelCase (datasetId, embedUrl). Ces chemins peuvent changer d'une version à l'autre ; le SDK les suit pour vous.
Questions fréquentes
Où trouver l'identifiant d'un dossier Drive ?
Dans l'URL du dossier : c'est la partie après /folders/.
Puis-je enregistrer un fichier CSV comme dataset ?
Oui, depuis Amazon S3 avec format="csv", ou depuis un drive avec son fileId.
Existe-t-il une description OpenAPI de cette API ? Pas pour les intégrateurs : le SDK et cette page font référence.