Envoyez des fichiers vous-même

Depuis le panel

Fichiers, puis Envoyer un fichier. Ce que vous choisissez arrive dans le dossier que vous regardez et vous récupérez le lien. Des octets identiques ne sont stockés qu’une fois : réenvoyer le même fichier ne coûte rien.

Créez un token

Tokens, puis Nouveau token. Liez-le à un serveur plutôt qu’à toute l’organisation, pour qu’une clé qui fuit ne puisse pas écrire partout. Le secret n’est affiché qu’une fois.

Le token d’API commence par fd_live_. Ce n’est pas la clé d’agent fda_live_ qui va dans server.cfg : celle-ci ne sert qu’à connecter la resource fivedock, et l’API d’envoi ne l’accepte pas.

files:write envoie, files:read relit, files:delete supprime, folders:write crée des dossiers, usage:read lit le stockage et le trafic. logs:write sert à envoyer les erreurs d’une application, pas des fichiers.

Envoyer en HTTP

Envoyez le fichier en multipart/form-data à POST /api/v3/file, l’adresse qu’utilise aussi Fivemanage. path est le dossier, créé à la volée, et filename remplace le nom de fichier de la partie.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=/branding"

{
  "status": "ok",
  "data": { "id": "8Kq2nR4t", "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png" },
  "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
  "filename": "logo.png",
  "mime_type": "image/png",
  "size": 48213,
  "fivedock": {
    "fileUrl": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
    "deduplicated": false,
    "folder": "/branding"
  }
}

url est le lien CDN, prêt à coller dans un écran de chargement ou un embed Discord, et il marche dès que la réponse arrive. fivedock.deduplicated indique que ces octets étaient déjà stockés : rien de neuf n’a été facturé. La réponse ci-dessus est abrégée.

Fichiers nommés et liens stables

Donnez une clé à un fichier, par exemple items/burger.png, et il est servi à un lien qui ne change jamais : https://cdn.fivedock.dev/o/my-city/items/burger.png, où my-city est le nom court de votre organisation. Envoyez à nouveau avec la même clé et le fichier derrière le lien est remplacé : une icône d’inventaire ou une image d’écran de chargement change sans toucher à un script ni à une base de données.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "key=items/burger.png"

# served at https://cdn.fivedock.dev/o/my-city/items/burger.png
# run it again with a new burger.png and the same link shows the new file

Les clés viennent du champ key de l’API d’envoi, de « Garder les noms de fichiers » dans le panel, des archives et de l’endpoint S3, où un objet placé en s3://my-city/items/burger.png est le fichier de clé items/burger.png. Dans le panel, un fichier à clé apparaît dans le dossier de sa clé, ici /items.

Le fichier remplacé est conservé 7 jours, puis purgé. Les liens à clé sont mis en cache 5 minutes, les joueurs voient donc une nouvelle version au bout de 5 minutes environ. Chaque fichier garde aussi son propre lien /f/, dont le contenu ne change jamais.

Les clés tirées de noms de fichiers sont nettoyées pour vous : les espaces deviennent -, et tout autre caractère qu’une clé ne peut pas contenir devient _. Une clé que vous envoyez vous-même à l’API doit déjà respecter les règles, sinon elle est refusée.

Envoyer tout un dossier en .zip ou .rar

Déposez un .zip ou un .rar dans la zone d’envoi du panel, ou envoyez-le à POST /api/v3/file/archive, et chaque fichier qu’il contient est stocké. « Garder les noms de fichiers » est activé par défaut pour les archives : burger.png décompressé dans items obtient le lien stable …/o/my-city/items/burger.png. Les dossiers de l’archive sont conservés.

curl -X POST https://api.fivedock.dev/api/v3/file/archive \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=items"

Une archive peut peser jusqu’à 512 Mio, avec au plus 5 000 fichiers et 4 Gio une fois décompressée. Les fichiers qu’on ne peut pas stocker, par exemple d’un type qu’on n’accepte pas ou protégés par mot de passe, reviennent dans une liste avec la raison. Pour des ensembles plus gros, synchronisez via l’endpoint S3.

Depuis votre propre uploader en HTML et JS

Ne mettez jamais un token dans le JavaScript du navigateur : quiconque ouvre la page le lit et envoie dans votre organisation. Recevez le fichier sur votre propre serveur, et gardez le token là-bas.

// your server, never the browser: the token stays here
app.post('/upload', upload.single('file'), async (req, res) => {
  const body = new FormData();
  body.append('file', new Blob([req.file.buffer]), req.file.originalname);
  body.append('path', '/player-shots');

  const answer = await fetch('https://api.fivedock.dev/api/v3/file', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.FIVEDOCK_TOKEN}` },
    body,
  });
  res.json(await answer.json());
});

// your page talks to your server, which holds the token
const body = new FormData();
body.append('file', input.files[0]);

const answer = await fetch('/upload', { method: 'POST', body });
const file = await answer.json();
image.src = file.url;

Si le fichier naît dans un navigateur ou une page NUI de FiveM, votre serveur peut plutôt créer un lien d’envoi à usage unique et transmettre ce lien. Le navigateur envoie directement à FiveDock et ne voit jamais le token.

Si vous voulez simplement que des joueurs vous envoient des fichiers sans écrire de code, utilisez plutôt un portail d’envoi : une page publique, limitée par adresse, avec un plafond quotidien et la modération devant.

L’endpoint compatible S3

Le même token est aussi un identifiant S3 : rclone, l’AWS CLI et la plupart des outils de sauvegarde peuvent y écrire. Utilisez l’adressage path-style.

rclone config create fivedock s3 \
  provider=Other \
  endpoint=https://s3.fivedock.dev \
  access_key_id=AKFD… \
  secret_access_key=… \
  force_path_style=true \
  region=auto

rclone copy ./branding fivedock:my-city/branding

aws --endpoint-url https://s3.fivedock.dev \
  s3 cp logo.png s3://my-city/branding/logo.png

Chaque objet que vous déposez est un fichier à clé : s3://my-city/branding/logo.png est servi à https://cdn.fivedock.dev/o/my-city/branding/logo.png.

Dossiers et rétention

Créez des dossiers dans le panel et déplacez-y des fichiers. La clé d’un fichier le suit : items/a.png déplacé vers /icons devient icons/a.png, et si cette clé est déjà prise, le déplacement est refusé pour ce fichier. La liste des fichiers a une vue liste et une vue grille, une recherche par nom et des filtres par type et par date d’ajout : dernières 24 heures, 7 jours, 30 jours ou depuis toujours.

Chaque dossier a une règle de rétention qui décide quand ses fichiers sont supprimés.

Servir ce que vous avez envoyé

Chaque fichier reçoit un lien CDN qui fonctionne dès que l’envoi a répondu. Les fichiers sont approuvés à l’envoi ; si la modération en retire un plus tard, son lien répond 404. Dans Réglages, la liste d’autorisation limite les sites qui peuvent intégrer vos fichiers.