Zugo: eksiksiz bir senkronizasyon uygulaması

Zugo, CIQRA’nın referans uygulamasıdır ve yalnızca bu sitede anlatılan herkese açık API’yi kullanır — özel bir arka kapı yoktur. Bir bayinin ikinci el araç feed’ini okur ve her aracı mağazaya ikinci-el-arac türünde bir metaobject kaydı olarak yayımlar; fotoğrafları da mağazanın medya kütüphanesine içe aktarılır.

Kaynak: CIQRA deposunda ciqra-saas/apps/Ciqra.Apps.Zugo/.

Yapı

Tek seferlik bir süreçtir: başlar, senkronize eder ve çıkar. Çalıştırmalar arasında durum tutmaz — durum mağazanın kendisidir ve her yazma işlemi anahtarlıdır; böylece yeniden çalıştırma kopya üretmek yerine aynı sonuca yakınsar.

Ayar (Zugo: bölümü)	Amacı
FeedBaseUrl, FeedUsername, FeedPassword	Bayi feed’i.
PlatformBaseUrl	CIQRA API’sine nereden ulaşılacağı.
PlatformHost	Host olarak gönderilen mağaza alan adı — mağazayı seçen budur.
ClientId, ClientSecret	Uygulamanın kimlik bilgileri.
MetaobjectType	Varsayılan ikinci-el-arac.
MaxRunDuration	Varsayılan 6 saat.

Eksik secret’ların tamamı, her başarısız çalıştırmada birer birer değil, başlangıçta tek seferde raporlanır.

Çağrılar, sırasıyla

1. Token. İstemci kimlik bilgileriyle POST /apps/token. Token önbelleğe alınır ve expiresIn dolmadan bir dakika önce yeniden istenir.
2. Fotoğraflar. Her araç için, Idempotency-Key: zugo:{runId}:{vehicle}:{chunk} ile en fazla 100 URL’lik parçalar halinde POST /apps/media/imports. Anahtarın çalıştırma başına olması bilinçlidir: bir çalıştırma içindeki yeniden deneme yeniden indirmek yerine önceki yanıtı tekrar oynatır; sonraki çalıştırma ise yeni bir istektir ve değişen fotoğrafları alır. URL’ye ve içerik hash’ine göre tekilleştirme sayesinde değişmeyen fotoğrafların maliyeti sıfırdır.
3. Kayıt. Aracın alanları ve galeri alanlarında dönen mediaAssetId’lerle PUT /custom-data/metaobjects/ikinci-el-arac/entries/{feed id}. Feed id’si handle’dır; böylece aynı araç her zaman aynı kayda düşer.

Hatalar araç başına yalıtılmıştır: fotoğrafları başarısız olan bir araç diğerlerini durdurmaz ve çalıştırmanın özeti her birini raporlar. 401, 403 ve 404 her biri olası nedeni belirten ayrı bir mesaj üretir (hatalı kimlik bilgileri, eksik bir scope, eksik bir metaobject türü).

İstediği scope’lar

write_media ve write_metaobjects — siparişler veya müşterilerle hiçbir ilgisi yoktur; böylece tüccarın onay ekranı uygulamanın tam olarak ne yaptığını gösterir.

Referans uygulamadaki bilinen kusur

Zugo PUT isteğinde yalnızca fields gönderir. Bu endpoint kaydın tamamını değiştirdiği ve ikinci-el-arac yayımlanabilir bir tür olduğu için, her yazma işlemi kaydı yayımlanmamış olarak saklar ve bu da onu vitrinden gizler. Uygulama henüz üretime dağıtılmadı; düzeltme sınırlamalar sayfasında takip ediliyor. Bu kalıbı kopyalarsanız publishedAt gönderin.

Neyi örnek almalı

• Her yazma işlemini kaynağınızdaki kararlı bir değerle anahtarlayın (handle = kaynak id’si).
• Durum kodunu değil, toplu endpoint’lerin satır bazlı sonuçlarını esas alın.
• 401’e tepki vermek yerine token’ı süresi dolmadan yenileyin.
• Idempotency anahtarlarını mantıksal işlem başına tutun ve yeniden denemelerde tekrar kullanın.