Ako ste se ikada mučili s API-jem prilikom pokušaja prijenosa slike, zvuka ili bilo kojeg dokumenta, znate da to nije tako jednostavno kao slanje običnog teksta. učitavanje datoteka pomoću HTTP zahtjeva To je temeljni stup za svakog programera koji radi s uslugama umjetne inteligencije, pohrana u oblaku ili sustave za prodaju karata, ali ako ne razumijete što se događa "ispod haube", vrlo je vjerojatno da ćete naići na frustrirajuće pogreške poslužitelja.
Da bi sve funkcioniralo glatko, ključno je razumjeti da binarni podaci ne funkcioniraju dobro s tradicionalnim tekstualnim formatima. Zato standard postoji. višedijelni/obrazac-podaci, rješenje osmišljeno za pakiranje različitih vrsta sadržaja u jednu prijavu, omogućujući poslužitelju da točno zna gdje završava tekstualno polje i gdje počinje niz bajtova datoteke.
Što je točno multipart/form-data i kako funkcionira?
U osnovi, to je vrsta sadržaja koja vam omogućuje slanje podataka obrasca koji miješaju tekstualne i binarne datoteke. Za razliku od application/x-www-form-urlencoded, što je standard za jednostavna tekstualna polja, višedijelni format dijeli tijelo zahtjeva na samostalni dijelovi.
Tajna cijelog ovog procesa je ono što se zove granicaOvo je jedinstveni, slučajni niz znakova koji djeluje kao granica. Poslužitelj koristi ovaj identifikator za odvajanje svakog bloka podataka. Ako pokušate konfigurirati zaglavlje Content-Type Ručno parsiranje bez uključivanja ove granice uzrokovat će zamrzavanje poslužitelja i vraćanje pogreške 400, jer neće znati kako parsirati informacije.
Usporedba metoda kodiranja
Često se pitamo treba li koristiti JSON s Base64 ili višedijelnim kodiranjem. Evo zašto višedijelno kodiranje obično pobjeđuje:
- application/x-www-form-urlencoded: Radi samo za jednostavne parove ključ-vrijednost. Pokušaj prijenosa binarne datoteke ovdje je praktički nemoguć zbog potrebe za izbjegavanjem URL-a, što ga čini krajnje neučinkovito.
- application/json con Base64: Moguće je, ali ima svoju cijenu. Pretvaranje datoteke u Base64 povećava njezinu veličinu za otprilike [nedostaje iznos]. 33%To rezultira većom potrošnjom propusnosti i povećanim opterećenjem CPU-a za poslužitelj.
- multipart/form-data: To je izvorna opcija za datoteke. Omogućuje vam njihovo slanje. binarnih podataka izravno bez čudnih kodiranja, što je najbrži i najlakši način.
Praktična primjena s Curlom
Curl je švicarski alat za testiranje API-ja i njegovih parametara -F To je najbrži način izvršavanja višedijelnih zahtjeva. Prilikom korištenja -FCurl obavlja prljavi posao za vas: uspostavlja POST metodu, konfigurira Content-Type i stvara jedinstvenu granicu automatski.
Za slanje tekstualnog polja jednostavno koristite -F "clave=valor"Ako želite prenijeti lokalnu datoteku, trebali biste koristiti simbol @: -F "campo=@/ruta/al/archivo.jpg". Možete čak navedite MIME tip ručno ako je API vrlo zahtjevan, dodavanjem ;type=image/jpeg na kraju putanje datoteke.
Primjeri koda u raznim jezicima
Ovisno o okruženju, način implementacije varira, ali logika je ista: nemojte forsirati zaglavlje sadržaja ako ga biblioteka već obrađuje.
Python s bibliotekom Requests
U Pythonu, biblioteka requests Zbog toga je sve vrlo jednostavno. Samo trebate definirati jedan rječnik za tekstualne podatke, a drugi za datoteke. Datoteke se moraju proslijediti kao skup koji sadrži naziv datoteke, objekt otvoren u binarnom načinu čitanja (rb) i MIME tip sadržaja.
Ključna stvar ovdje je da prilikom prosljeđivanja parametara data y files istovremeno, knjižara automatski konfigurira granicusprječavajući da zahtjev stigne na poslužitelj u oštećenom stanju.
JavaScript i Node.js
U pregledniku koristimo objekt FormDataJednostavno dodajemo polja s append() i prosljeđujemo objekt body funkcije fetch. To je ključno NE postavljajte ručno vrstu sadržajaAko to učinite, izbrisat ćete granicu koju preglednik generira prema zadanim postavkama i učitavanje neće uspjeti.
U Node.js-u je situacija slična, ali obično koristimo modul form-data y axiosU ovom slučaju potrebno je pozvati form.getHeaders() uključiti ispravne naslove u zahtjev.
Primjeri iz stvarnog svijeta: Od Sore 2 do Google diska
Različite usluge implementiraju ovaj standard na malo drugačije načine. Na primjer, API od Sora 2 Zahtijeva da rezolucija prenesene slike točno odgovara parametru veličine videa kako bi se izbjegle pogreške u obradi.
S druge strane, API od Google disk Nudi tri razine prijenosa. Pojedinačni prijenos je za male datoteke bez metapodataka. Višedijelni prijenos omogućuje vam slanje metapodaci u JSON-u i datoteci u jednom zahtjevu (prema RFC 2387). Za velike datoteke Google preporučuje obnovljiva naplataslično kao što prijenos komprimiranih datotekašto vam omogućuje oporavak prijenosa ako se veza prekine, izbjegavajući pokretanje ispočetka.
Upravljanje greškama i optimizacija
Ako primite grešku 413 (Preveliki korisni teret), to znači da datoteka premašuje ograničenje konfigurirano na poslužitelju (kao što je zadano ograničenje od 1 MB u Nginxu). Da biste to popravili, možete komprimirati datoteke ili implementirati segmentirano učitavanje.
Drugi uobičajeni problem je greška 400 kada granica nedostaje. Uvijek imajte na umu da granica mora biti jedinstveni niz. ne pojavljuje se u tijelu poruke kako biste izbjegli zbunjivanje parsera poslužitelja. Za otklanjanje pogrešaka koristite curl -v To je najbolja opcija jer vam omogućuje da točno vidite kako je zahtjev strukturiran prije nego što napusti vaše računalo.
U konačnici, ovladavanje prijenosom binarnih podataka pomoću ovog protokola omogućuje učinkovitu integraciju složene umjetne inteligencije i usluga pohrane. Ključ leži u... koristite prave alate kao što su FormData ili biblioteka Requests, uvijek delegirajući upravljanje granicama HTTP klijentu kako bi se osigurala nesmetana komunikacija s API-jem bez pogrešaka pri parsiranju.
