api.tipmoto.com » Dokumentace API » Referenční » Fotografie

Fotografie

Práce s fotkami reflektuje různé systémy, takže možnosti práce s nimi jsou velmi variabilní.
Fotografie můžete posílat ve formátech JPEG, PNG, GIF, BMP, TIFF a WebP (zpracování popisuje agenda photo)

Na úrovni inzerátu

Zasíláte-li na úrovni inzerátu strukturu photos dochází automaticky ke zpracování fotografií tak, že se u inzerátu aktualizují fotky, aby obsahovaly pouze fotografie v této struktuře (smaže staré, přidá nové).
Aktualizace fotky je možné řídit parametrem stamp - uvedete vlastní parametr, který, když se změní, dojde i při stejné URL k aktualizaci fotky. Pokud se Vám při změně fotky mění i URL, není nutné stamp využívat – nová URL je ale nová fotka, která se přidá na konec galerie (výjimkou je výměna hlavní fotky, viz Pořadí a hlavní fotka); výměnu na stejném místě udělá změna stamp. Pokud jej využíváte, doporučujeme uvádět např. datetime, filesize, hash souboru apod.
Na úrovni inzerátu jsou pro photos i tři možné atributy:

• ignoreimport="true" - struktura photos se ignoruje
• forceupdate="true" - vynutí aktualizaci všech fotografií bez ohledu na změnu URL či stamp (všechny fotky dostanou nová ID, viz níže)
• reorder="true" - galerie se seřadí podle pořadí fotek v photos (viz Pořadí a hlavní fotka)

Pomocí agendy photo

Pomocí agendy photo je možné přidávat/editovat/mazat vždy po jedné fotografii.
Uvádění ID fotografie u inzerátu není povinné - čtěte však chování u jednotlivých možností!

1. Přidání/editace fotografií pomocí url
Pokud uvádíte tag url, je chování následující:

• Je-li uvedeno ID fotografie, pak se kontroluje, zdali je u této fotografie stejná url, stamp a případně dojde pouze k aktualizaci dané fotografie.
• Není-li uvedeno ID fotografie, pak se kontroluje, zdali existuje u tohoto inzerátu stejná url a případně se dle stamp či forceupdate aktualizuje tento obrázek. Není-li adresa nalezena, založí se nový obrázek

2. Přidání/editace fotografií pomocí content
Pokud uvádíte tag content, je chování následující:

• Je-li uvedeno ID fotografie, pak se vždy přepíše obsahem fotografie uvedeným v content
• Není-li uvedeno ID fotografie, vždy se založí nový obrázek

3. Přidání/editace fotografií pomocí raw-data
Místo XML struktury můžete zaslat v PUT požadavku přímo JPG data, je však nutné uvést URL parametr ?raw-data=true

• Je-li uvedeno ID fotografie, pak se vždy přepíše obsahem RAW-DATA
• Není-li uvedeno ID fotografie, vždy se založí nový obrázek

Doporučení: Vzhledem k tomu, že založení/přidání fotografie záleží na kontextu dat, není vracena hlavička Location:, avšak vrací se vždy struktura, kde je uvedeno ID fotografie, která byla změněna/vložena.

Smazání fotografie
Je možné buď posláním HTTP operace DELETE nebo zasláním PUT/POST operace s tagem <photo action="delete">

Pořadí a hlavní fotka

Pořadí fotek v galerii a hlavní fotka (ta, která se ukazuje v přehledu inzerátů) jsou jeden mechanismus: hlavní fotka je vždy na pozici 1. Stejná pravidla platí pro všechny cesty – import inzerátu se strukturou photos, agendu photo i podagendu photo/sort. Při čtení je pozice fotky v prvku sortOrder (1 = hlavní fotka), ve stejném pořadí, v jakém fotky ukazuje web.

Hodnoty main (všude stejně): 1 nebo true = hlavní fotka, 0 nebo false = není hlavní, prázdná hodnota = neuvedeno. Doporučujeme psát malá písmena. Jiná hodnota se ignoruje a v odpovědi přijde warning.

Při importu inzerátu (photos) se pořadím hýbe jen tehdy, když o to výslovně požádáte:

Co pošlete	Co se stane
jen seznam fotek, bez main = 1, sortOrder i reorder	pořadí ani hlavní fotka se nemění; nové fotky se přidají na konec, fotky dříve nahrané přes API, které v seznamu chybí, se smažou a ostatní se k sobě posunou
totéž, ale inzerát zatím žádné fotky nemá	pořadí se převezme z photos, první fotka je hlavní
main = 1 u některé fotky	fotka se stane hlavní a přesune se na pozici 1, ostatní fotky si drží vzájemné pořadí; má-li main = 1 více fotek, platí první z nich
main = 0 bez sortOrder	samo o sobě nic nemění – jinou hlavní fotku určíte jen tak, že ji označíte main = 1
sortOrder u některé fotky	fotka se postaví na uvedenou pozici (absolutní pozice, viz níže)
<photos reorder="true">	galerie se seřadí podle pořadí fotek v photos; fotky, které tam nejsou (např. nahrané v administraci), přijdou za ně v dosavadním pořadí; main a sortOrder platí i tady
import smaže dosavadní hlavní fotku (už není v photos) a neurčuje hlavní fotku ani pořadí (žádné main = 1, sortOrder ani reorder)	hlavní se stane první nově přidaná fotka a dostane pozici 1 – titulní fotku tak lze vyměnit i novou URL; nepřibyla-li žádná nová fotka, stane se hlavní další fotka v dosavadním pořadí

sortOrder je absolutní pozice. Fotka se postaví na uvedené místo a ostatní fotky vyplní zbylá místa – bez reorder ve svém dosavadním pořadí, s reorder="true" v pořadí z photos. Číslo větší než počet fotek znamená konec galerie. Chce-li stejnou pozici více fotek, dostane ji první z nich a další jdou na nejbližší volná místa za ní. Příklad: galerie A, B, C, D a fotce C pošlete sortOrder = 2 → výsledek A, C, B, D.
sortOrder = 1 dělá z fotky hlavní. sortOrder jiné než 1 spolu s main = 1, nebo 1 spolu s main = 0 je chyba a požadavek se nezpracuje.

Výměna fotky a ID

• Výměna přes stamp při importu inzerátu (stejná URL a jiný stamp, nebo forceupdate="true"): fotka se stáhne znovu a dostane nové ID (a tím i novou adresu u nás); pozice v galerii i to, zda je hlavní, zůstanou. Když se stažení nepovede, zůstane původní fotka a import se o výměnu pokusí příště znovu.
• Výměna novou URL při importu inzerátu: pro API je to nová fotka – stará se smaže a nová se přidá na konec galerie (výjimka pro hlavní fotku viz tabulka výše). Chcete-li fotku vyměnit na stejném místě, ponechte URL a změňte stamp.
• Náhrada přes PUT /photo/{id} (agenda photo): obsah se přepíše pod stejným ID, pozice v galerii i to, zda je hlavní, zůstanou.
• Po každém přidání nebo smazání fotky kteroukoli cestou se pořadí dorovná: pozice jsou vždy souvislé od 1 a hlavní fotka je právě jedna. Vzájemné pořadí fotek se tím nemění.

Pozor na forceupdate="true": přestahuje všechny fotky inzerátu a všem přidělí nová ID i nové URL. Posílejte ho jen výjimečně (např. při změně systému), ne při každém importu.

Pořadí více fotek najednou bez posílání celého inzerátu změníte podagendou photo/sort, pozici nebo hlavní fotku jedné fotky přes PUT /photo/{id} se sortOrder nebo main.

Kontaktujte nás