Failid

Failiparameetrid võimaldavad objektidel salvestada manuseid, dokumente, pilte ja muid binaarseid andmeid. Failid salvestatakse objektisalvestusse (S3-ühilduv) ja neile pääseb ligi allkirjastatud, ajalimiitidega URLide kaudu.

Failide üleslaadimise lubamiseks objektitüübil lisa parameetri definitsioon type: file kujul.

Failiparameetri struktuur

Failiparameetri väärtusel on kolm kohustuslikku metaandmete välja:

Väli	Kirjeldus
filename	Faili algne nimi (nt cover.jpg, report.pdf)
filesize	Suurus baitides
filetype	MIME tüüp (nt image/jpeg, application/pdf)

Kõik kolm peavad olema failiparameetri loomisel olemas. Igal failiparameetril on oma unikaalne salvestusasukoht, mida identifitseerib selle _id.

Üleslaadimise protsess

Failide üleslaadimine kasutab turvalist kahesammulist voogu:

1. samm — Loo failiparameeter

Postita faili metaandmed objektile. API vastab parameetriobjektiga, mis sisaldab välja upload allkirjastatud URL-i ja nõutavate päistega.

{
  "type": "photo",
  "filename": "cover.jpg",
  "filesize": 1937,
  "filetype": "image/jpeg"
}

Vastus:

{
  "_id": "507f1f77bcf86cd799439011",
  "type": "photo",
  "filename": "cover.jpg",
  "filesize": 1937,
  "filetype": "image/jpeg",
  "upload": {
    "url": "https://s3.amazonaws.com/bucket/path?signature...",
    "method": "PUT",
    "headers": {
      "ACL": "private",
      "Content-Disposition": "inline;filename=\"cover.jpg\"",
      "Content-Length": 1937,
      "Content-Type": "image/jpeg"
    }
  }
}

2. samm — Lae fail üles

PUT-i faili sisu otse allkirjastatud URL-ile, kasutades täpselt vastuses tagastatud päiseid — kõik neli on nõutavad:

curl -X PUT "SIGNED_S3_URL" \
  -H "ACL: private" \
  -H "Content-Disposition: inline;filename=\"cover.jpg\"" \
  -H "Content-Length: 1937" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@cover.jpg"

Allkirjastatud üleslaadimise URL aegub 60 sekundi pärast. Lõpeta S3 PUT enne aegumist. Ühes POST-is on võimalik luua mitu failiparameetrit — igaüks saab vastuses oma upload objekti.

WARNING

Kui üleslaadimise URL aegub enne S3 PUT-i lõpetamist, kustuta parameeter ja alusta otsast.

Allalaadimise protsess

Faili allalaadimiseks tee GET päring parameetri ID järgi:

GET /api/{db}/property/{_id}

Vastus sisaldab välja url ajalimiitidega allkirjastatud URL-iga — kehtib 60 sekundit. Ära vahemällu salvesta ega jaga seda; genereeri iga kord uus.

Otsese brauseri allalaadimise käivitamiseks lisa ?download=true — see suunab kohe allkirjastatud URL-ile.

Pisipildid

Objekti pisipilt

Loo objekti photo parameetri esimesest failist ruudukujuline pisipilt:

GET /api/{db}/entity/{_id}/thumbnail/{size}

Endpoint võtab esimese photo faili, renderdab selle, kärbib keskelt ruuduks (cover-sobitus) ja toodab JPEG-i. Toetatud on nii pildid (image/*, välja arvatud SVG) kui ka PDF-failid — PDF-i puhul renderdatakse esimene lehekülg.

Tee size peab olema üks lubatud väärtustest (ruudu laius ja kõrgus pikslites):

50, 200, 400

Mis tahes muu väärtus tagastab 400. Lubatud väärtuste loend piirab failikohaste vahemällu salvestatud variantide arvu.

Vastus sisaldab ajalimiidiga allkirjastatud välja url (kehtib 60 sekundit), sama kujul nagu faili allalaadimine:

{
  "url": "https://s3.amazonaws.com/bucket/path?signature..."
}

Loodud pisipildid salvestatakse objektihoidlasse, seega on esimene päring antud faili ja suuruse kohta aeglasem (genereerimine) ning järgmised serveeritakse vahemälust. Igal päringul kehtivad samad juurdepääsureeglid mis lähteobjektil.

Vastus	Tähendus
200	JSON { url } allkirjastatud pisipildi URL-iga
400	Vigane size, toetamata failitüüp või faili ei õnnestunud dekodeerida
403	Puudub juurdepääs objektile
404	Objekti ei leitud või sellel puudub photo

Parameetri pisipilt

Loo ruudukujuline pisipilt mis tahes üksikust failiparameetrist — mitte ainult photo-st — viidatuna selle parameetri _id järgi:

GET /api/{db}/property/{_id}/thumbnail/{size}

Kui objekti endpoint kasutab alati objekti esimest photo faili, siis see endpoint teeb pisipildi konkreetsest failiparameetrist, millele viitad. Muus osas on käitumine identne: kärbib keskelt ruuduks (cover-sobitus) ja toodab JPEG-i. Toetatud on nii pildid (image/*) kui ka PDF-failid — PDF-i puhul renderdatakse esimene lehekülg. See toidab kasutajaliideses failinime kohal hõljudes kuvatavat pisipildi eelvaadet.

Tee size peab olema üks lubatud väärtustest (ruudu laius ja kõrgus pikslites):

50, 200, 400

Mis tahes muu väärtus tagastab 400.

Vastus sisaldab ajalimiidiga allkirjastatud välja url (kehtib 60 sekundit), sama kujul nagu faili allalaadimine:

{
  "url": "https://s3.amazonaws.com/bucket/path?signature..."
}

Loodud pisipildid salvestatakse objektihoidlasse, seega on esimene päring antud parameetri ja suuruse kohta aeglasem (genereerimine) ning järgmised serveeritakse vahemälust. Igal päringul kehtivad parameetri juurdepääsureeglid — sama juurdepääsukontroll nagu GET /api/{db}/property/{_id}.

Vastus	Tähendus
200	JSON { url } allkirjastatud pisipildi URL-iga
400	Vigane size, parameeter ei ole eelvaadatav fail (ei ole pilt ega PDF) või faili ei õnnestunud dekodeerida
403	Puudub juurdepääs parameetrile
404	Parameetrit ei leitud

Failiparameetri kustutamine

Kustuta failiparameeter samal viisil nagu mis tahes muu parameetriväärtus:

DELETE /api/{db}/property/{_id}

See teeb parameetrikirje pehmelt kustutatuks (märgistatuna deleted.at ja deleted.by-ga). Aluseks olevat faili objektisalvestuses ei eemaldata — kustutatakse ainult parameetriviide.