Requêtes HTTP

Le bloc request d'une source de données déclarative en mode poll décrit l'appel que la plateforme effectue à chaque tick. url, method, headers et query en sont les parties évidentes. Cette page couvre les trois champs qui déterminent si une véritable API fournisseur fonctionne ou non :

• request.auth — où est placé le credential désigné par authRef : un token bearer, un en-tête personnalisé, ou un paramètre de requête.
• request.body — le payload d'un POST, GraphQL compris.
• response.format — une indication de décodage explicite (json, xml, csv, jsonl) lorsqu'un fournisseur étiquette mal son propre payload.

Ces trois champs sont optionnels. Un manifeste écrit avant leur existence est analysé et se comporte exactement comme auparavant : authRef seul signifie Authorization: Bearer <apiKey>, et le format de réponse est détecté à partir des signaux du payload lui-même.

Où part la requête — url, ou l'endpoint de la connexion

Une requête désigne son endpoint exactement une fois :

• url — une URL https:// fixe, identique pour chaque organisation qui installe l'extension.
• endpointRef + path — l'URL de base vient de la connexion créée par un administrateur : endpointRef est la clé du champ de configuration { type: 'url', purpose: 'endpoint' } de l'extension, et path y est ajouté.

request: {
  endpointRef: 'baseUrl',
  path: '/api/states',
  authRef: 'token',
  auth: { placement: 'bearer' },
}

Un chemin déjà présent dans l'URL de la connexion est conservé (https://proxy.example.com/ha + /api/states). path commence par / et ne porte ni query string, ni fragment, ni .. — les paramètres statiques vont dans query, comme d'habitude. Tout ce qui suit s'applique aux deux formes. Voir Endpoints fournis par une connexion pour déclarer le champ et ce que saisit un administrateur.

request.auth — où va le credential

authRef indique quel credential stocké utiliser. auth indique où le placer. Définir auth sans authRef est une erreur de validation — il n'y aurait aucun credential à placer.

Quel champ de credential

credential désigne un champ de la connexion que la plateforme a résolue pour vous — jamais une valeur secrète. Chaque placement porte un seul secret opaque : il n'y a donc exactement que deux champs possibles :

Bearer (le comportement par défaut)

Omettez complètement auth et vous obtenez ceci. Ne l'écrivez explicitement que pour choisir un autre champ :

request: {
  url: 'https://api.example.com/v1/records',
  authRef: 'example-api-key',
  auth: { placement: 'bearer', credential: 'accessToken' },
}

Un en-tête personnalisé

Le cas courant x-api-key. prefix est écrit tel quel devant le secret — incluez l'espace final si le fournisseur l'attend :

request: {
  url: 'https://api.example.com/v1/records',
  authRef: 'example-api-key',
  auth: { placement: 'header', name: 'x-api-key' },
}

Un paramètre de requête

Certaines API anciennes attendent la clé dans l'URL :

request: {
  url: 'https://api.example.com/v1/records',
  query: { limit: '500' },
  authRef: 'example-api-key',
  auth: { placement: 'query', name: 'api_key' },
}

name doit n'utiliser que des caractères non réservés d'URL (lettres, chiffres, ., _, ~, -) et ne peut pas entrer en collision avec une clé déjà présente dans request.query ni avec un paramètre déjà écrit dans url (?api_key=...) — le credential écraserait silencieusement votre paramètre statique, exactement le genre de bug que l'on découvre en production. Renommez l'un des deux.

request.body — payloads POST

Un corps de requête n'est valide que si method vaut 'POST'. Un GET accompagné d'un corps est rejeté au moment du build plutôt qu'envoyé puis ignoré silencieusement.

JSON

request: {
  url: 'https://api.example.com/v1/search',
  method: 'POST',
  body: { kind: 'json', value: { since: '2026-01-01', pageSize: 500 } },
}

value accepte n'importe quelle valeur JSON — objet, tableau, chaîne, nombre, booléen ou null. Elle est sérialisée avec JSON.stringify et envoyée avec Content-Type: application/json.

GraphQL

GraphQL n'est pas un kind distinct. C'est un corps JSON dont la valeur porte query et variables :

ingest: {
  mode: 'poll',
  intervalSec: 300,
  request: {
    url: 'https://api.example.com/graphql',
    method: 'POST',
    authRef: 'example-api-key',
    body: {
      kind: 'json',
      value: {
        query: 'query Vessels($limit: Int!) { vessels(limit: $limit) { mmsi lat lon } }',
        variables: { limit: 500 },
      },
    },
  },
  response: { itemsPath: '$.data.vessels' },
  mapping: {
    mmsi: { path: 'mmsi' },
    latitude: { path: 'lat' },
    longitude: { path: 'lon' },
  },
}

Notez qu'itemsPath traverse l'enveloppe data de GraphQL. Une réponse GraphQL en erreur ne comporte pas de tableau data.vessels : le tick échoue donc bruyamment au lieu d'écrire zéro ligne.

Texte

Pour tout ce qui n'est pas du JSON. contentType est requis — rien ne permet de le déduire :

request: {
  url: 'https://api.example.com/v1/query',
  method: 'POST',
  body: {
    kind: 'text',
    value: 'from(bucket:"telemetry") |> range(start:-5m)',
    contentType: 'application/vnd.flux',
  },
}

response.format — fixer le décodage

Par défaut, la plateforme détecte le format du corps à partir du Content-Type de la réponse, puis de l'extension de l'URL, puis du premier octet non blanc. C'est format: 'auto', et c'est ce que vous obtenez si vous ne dites rien.

Définissez format lorsqu'un fournisseur se trompe sur son propre payload — un export CSV servi en application/octet-stream, un flux JSONL étiqueté text/plain, ou un flux RSS servi en application/json :

response: { itemsPath: '$', format: 'csv' }

Il n'existe délibérément aucune valeur rss ni atom : les trois s'analysent de façon identique, et la seule différence entre elles est le chemin d'entrée que votre itemsPath nomme déjà. Voir Formats de réponse pour la présentation complète des flux.

Un format explicite est une instruction de décodage, pas une suggestion : si le corps ne peut pas être lu ainsi, le tick échoue avec une erreur d'analyse au lieu de tenter une seconde hypothèse.

Les credentials n'atteignent jamais un journal

Un credential résolu pour un tick n'existe que le temps de cette requête.

• Le manifeste porte des noms de champs, jamais des valeurs. .strict() sur le bloc request rejette tout champ superflu, et un en-tête Authorization en clair est rejeté d'office.
• Avec placement: 'query', le secret se trouve nécessairement dans l'URL. Chaque URL que la plateforme écrit dans une ligne de journal ou un message d'erreur voit ce paramètre remplacé par *** ; les paramètres statiques qui l'entourent sont conservés, de sorte que le journal indique toujours quel appel a échoué.
• Une erreur levée parce qu'une connexion ne comporte pas le champ que vous avez désigné indique quel champ était absent (credentials.accessToken), jamais le contenu d'un autre champ.

Récapitulatif de la validation

Ce sont des erreurs détectées au build, par extension build, avant qu'une archive ne soit jamais téléversée :