Wysyłaj pliki samodzielnie

Z panelu

Pliki, potem „Wyślij plik”. To, co wybierzesz, trafi do folderu, który masz otwarty, a Ty dostaniesz link. Identyczne pliki zapisujemy raz, więc ponowne wysłanie tego samego nic nie kosztuje.

Wygeneruj token

Tokeny, potem „Nowy token”. Przypisz go do jednego serwera, a nie do całej organizacji, żeby wyciek klucza nie dawał zapisu wszędzie. Sekret pokazujemy tylko raz.

Token API zaczyna się od fd_live_. To nie jest klucz agenta fda_live_ z server.cfg: tamten tylko łączy zasób fivedock, a API wysyłania go nie przyjmuje.

files:write wysyła, files:read odczytuje, files:delete usuwa, folders:write tworzy foldery, usage:read czyta zużycie miejsca i transferu. logs:write służy do wysyłania błędów z aplikacji, nie do plików.

Wysyłka przez HTTP

Wyślij plik jako multipart/form-data na POST /api/v3/file, ten sam adres, którego używa Fivemanage. path to folder, tworzony w locie, a filename nadpisuje nazwę pliku z części.

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 to link z CDN, gotowy do wklejenia w loading screen albo w embed na Discordzie, i działa od razu, gdy przyjdzie odpowiedź. fivedock.deduplicated mówi, że te bajty już u nas były, więc nic nowego nie doliczyliśmy. Odpowiedź powyżej jest skrócona.

Nazwane pliki i stałe linki

Nadaj plikowi klucz, na przykład items/burger.png, a dostanie link, który się nie zmienia: https://cdn.fivedock.dev/o/my-city/items/burger.png, gdzie my-city to krótka nazwa Twojej organizacji. Wyślij plik z tym samym kluczem jeszcze raz, a pod linkiem pojawi się nowy plik. Ikonę przedmiotu albo grafikę na loading screen podmienisz więc bez ruszania skryptów i bazy.

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

Klucze biorą się z pola key w API wysyłania, z opcji „Zachowaj nazwy plików” w panelu, z archiwów i z endpointu S3, gdzie obiekt s3://my-city/items/burger.png to plik z kluczem items/burger.png. W panelu plik z kluczem widać w folderze wynikającym z klucza, tutaj /items.

Podmieniony plik jest trzymany jeszcze 7 dni, a potem usuwany. Linki z kluczem są trzymane w cache przez 5 minut, więc gracze zobaczą nową wersję po około 5 minutach. Każdy plik ma też własny link /f/, którego zawartość nigdy się nie zmienia.

Klucze tworzone z nazw plików poprawiamy za Ciebie: spacje zamieniamy na -, a każdy inny znak, którego klucz nie może zawierać, na _. Klucz, który sam wysyłasz do API, musi już spełniać zasady, inaczej zostanie odrzucony.

Wyślij cały folder jako .zip albo .rar

Upuść plik .zip albo .rar na pole wysyłania w panelu albo wyślij go na POST /api/v3/file/archive, a zapiszemy każdy plik ze środka. Przy archiwach opcja „Zachowaj nazwy plików” jest domyślnie włączona, więc burger.png rozpakowany do items dostaje stały link …/o/my-city/items/burger.png. Foldery z archiwum zostają zachowane.

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

Archiwum może mieć do 512 MiB, najwyżej 5000 plików i 4 GiB po rozpakowaniu. Pliki, których nie możemy zapisać, na przykład w nieobsługiwanym formacie albo zabezpieczone hasłem, wracają na liście razem z powodem. Większe zbiory synchronizuj przez endpoint S3.

Z własnego uploadera w HTML i JS

Nigdy nie wstawiaj tokenu do JavaScriptu po stronie przeglądarki: każdy, kto otworzy stronę, odczyta go i wyśle pliki do Twojej organizacji. Przyjmij plik na własnym serwerze i tam trzymaj token.

// 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;

Jeśli plik powstaje w przeglądarce albo na stronie NUI w FiveM, Twój serwer może zamiast tego wygenerować jednorazowy link do wysyłki i przekazać właśnie jego. Przeglądarka wysyła plik prosto do FiveDock i nigdy nie widzi tokenu.

Jeśli chodzi Ci o to, żeby gracze wysyłali pliki bez pisania kodu, użyj portalu do wysyłania plików: to publiczna strona z limitem zapytań na adres, dziennym limitem i moderacją przed publikacją.

Endpoint zgodny z S3

Ten sam token jest też poświadczeniem S3, więc rclone, aws CLI i większość narzędzi do kopii potrafi tu pisać. Używaj adresowania 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

Każdy obiekt, który wgrasz, jest plikiem z kluczem, więc s3://my-city/branding/logo.png jest dostępny pod https://cdn.fivedock.dev/o/my-city/branding/logo.png.

Foldery i retencja

Twórz foldery w panelu i przenoś między nimi pliki. Klucz pliku przenosi się razem z nim: items/a.png przeniesiony do /icons staje się icons/a.png, a jeśli ten klucz jest zajęty, przeniesienie tego pliku zostanie odrzucone. Lista plików ma widok listy i siatki, wyszukiwanie po nazwie oraz filtry typu i daty dodania: ostatnie 24 godziny, 7 dni, 30 dni albo cały czas.

Każdy folder ma zasadę retencji, która decyduje, kiedy jego pliki są usuwane.

Udostępnianie tego, co wysłałeś

Każdy plik dostaje link z CDN, który działa od razu po zakończeniu wysyłki. Pliki są zatwierdzane przy wysyłce; jeśli moderacja zdejmie któryś później, jego link odpowie 404. Które strony mogą osadzać Twoje pliki, ograniczysz listą dozwolonych w Ustawieniach.