Function’ları metafield (meta alan) ile yapılandırmak: kuralı yeni sürüm yayınlamadan değiştirin

Shopify Function, ödeme sayfasının içinde çalışan derlenmiş koddur. Eşik, ürün listesi ya da hata mesajı bu kodun içine yazılmışsa, her iş değişikliği bir geliştirici işine ve yeni bir yayına dönüşür. Çözüm, mantığı Function’da, ayarları ise mağaza sahibinin ya da bir yönetim ekranının değiştirebileceği metafield’larda tutmaktır.

Bir Function ayarlarını nasıl görür?

Bir Function yalnızca GraphQL girdi sorgusunun istediği veriyi alır. Metafield’lar bu verinin parçasıdır. Shopify’ın dokümantasyonuna göre tüm Function API’leri, şemalarının bir parçası olarak function sahibine ve onun metafield’larına erişim sağlar. Sahip, mağaza sahibinin Function’ı açarken oluşturduğu nesnedir: bir indirim, bir doğrulama, bir teslimat özelleştirmesi ya da bir ödeme özelleştirmesi.

Örneğin Cart and Checkout Validation girdisi, aşağıdaki dördü dahil birkaç nesne türündeki metafield’ları okuyabilir:

Sahip metafield’ları bir kuralın ayarlarını bir arada tutar ve mağaza sahibinin oluşturduğu her sahip, örneğin her indirim, kendi ayarlarını taşır. Kaynak metafield’ları ise mağaza sahibinin zaten ürün ürün yönettiği verilere uygundur.

Her Function API’si girdide kendi sahibini adlandırır; bu yüzden yapılandırma alanı öngörülebilir bir yerde durur:

Kendi namespace’inizde tek bir JSON metafield

Yapılandırmada iç içe ya da tekrarlanan veri varsa Shopify tek bir JSON metafield önerir; çünkü yönetmesi ve sorgulaması daha kolaydır. Namespace’te ayrılmış `$app` önekini kullanın; böylece diğer uygulamalar bu metafield’ı kullanamaz. Function da ayrıştırılmış değeri jsonValue ile okur:

query RunInput {
  cart {
    lines {
      quantity
      merchandise {
        ... on ProductVariant {
          id
        }
      }
    }
  }
  validation {
    metafield(namespace: "$app:product-limits", key: "product-limits-values") {
      jsonValue
    }
  }
}

Metafield, GraphQL Admin API üzerinden yazılır; ya sahip oluşturulurken (örneğin discountAutomaticAppCreate ile) ya da sonradan bir metafield güncellemesiyle.

Girdi sorgusu değişkenleri: sorgunun kendisini değiştiren ayarlar

Bazı ayarlar yalnızca mantığı beslemez; Function’ın neyi isteyeceğine de karar verir. “Bu koleksiyonlardaki ürünler” için yazılmış bir kural, koleksiyon ID’lerine sorgunun içinde, inAnyCollection gibi alanlarda ihtiyaç duyar. Bunu girdi sorgusu değişkenleri çözer: Shopify bu değişkenleri function sahibindeki bir JSON metafield’ı okuyarak doldurur; buradaki her üst düzey anahtar bir değişken adıdır. Namespace ve anahtar, extension’ın shopify.extension.toml dosyasında, extensions.input.variables altında tanımlanır.

İki kısıt var: yalnızca JSON metafield’lar desteklenir ve 100’den fazla öğe içeren bir liste değişkeni hata döndürür. Aynı değişkenler sayesinde tek bir Function, yeniden yayına alınmadan, farklı koleksiyonlara sahip birkaç mağazada çalışabilir.

Mağaza sahibine bir ayar ekranı vermek

Metafield’lar ancak geliştirici olmayan biri de onları düzenleyebiliyorsa “yayına almadan değişiklik” sağlar. Bir admin UI extension, bu ekranı Shopify yönetim panelinin içinde sunar:

• Doğrulama Function’ları için admin.settings.validation.render; mağaza sahipleri buna Settings > Checkout > Checkout rules üzerinden ulaşır.
• İndirim Function’ları için, indirimin ayrıntılar sayfasında admin.discount-details.function-settings.render.
• Sipariş yönlendirme kuralları için admin.settings.order-routing-rule.render.

Extension metafield’ı applyMetafieldChange ile yazar; Shopify’ın function ayarları bileşeni de form düzenini sağlar ve yönetim panelinin kaydet çubuğuna bağlanır. Mağaza sahibi Function’ın kaldıramayacağı bir eşiği kaydedemesin diye formdaki her alanı, örneğin asgari ve azami değerle, doğrulayın.

Örnek: ürün başına adet sınırları

Shopify’ın karmaşık doğrulama kuralları için hazırladığı kendi eğitimi bu deseni baştan sona izler. Mağaza sahibi bir yönetim ekranında her ürün varyantı için azami adedi belirler. Uygulama tüm sınırları doğrulama üzerindeki $app:product-limits namespace’inde tek bir JSON değeri olarak saklar. Ödeme sırasında doğrulama Function’ı bu değeri okur, her sepet satırının adediyle karşılaştırır ve sınırını aşan her satır için bir hata döndürür.

Saklanan değer, Function’ın ayrıştırdığı sıradan bir JSON’dır. Basit bir yapı varyant ID’lerini sınırlarla eşler:

{
  "gid://shopify/ProductVariant/1234567890": 2,
  "gid://shopify/ProductVariant/1234567891": 5
}

Bir sınırı değiştirmek için mağaza sahibi Settings > Checkout > Checkout rules altında sayıyı düzenleyip kaydeder. Kod değişikliği yok, yayına alma yok. Dikkat edilmesi gereken tek şey büyümedir: böyle bir eşleme her yeni ürünle uzar ve değer 10.000 baytı geçtiğinde Function onu artık almaz. Büyük kataloglarda, sahip üzerindeki tek bir eşleme yerine her ürün için bir ürün varyantı metafield’ı daha iyi ölçeklenir.

Tasarımda hesaba katılacak sınırlar

• Boyut. 10.000 baytı aşan metafield değerleri girdiye dahil edilmez. Büyük yapılandırmaları birkaç metafield’a bölün.
• Sorgu. Girdi sorgusu (yorumlar hariç) en fazla 3.000 bayt ve en fazla 30 maliyet olabilir; liste argümanları 100 öğeyi geçemez.
• Girdi. 200 satıra kadar sepetlerde Function girdisinin tamamı 128 kB ile sınırlıdır; yani yapılandırma, sepet verisiyle aynı alanı paylaşır.
• Mantık. Metafield’lar davranışı değil ayarları değiştirir. Yeni bir kural türü yine kod değişikliği ve uygulamanın yeniden yayına alınmasını gerektirir.

Yapılandırma biçimini güvenle değiştirmek

Er ya da geç ayarların biçimi değişir: tek bir eşik, kademelerden oluşan bir listeye dönüşür. Shopify’ın dokümantasyonu paralel değişiklik (genişlet ve daralt) desenini önerir: Function hem eski hem yeni metafield’ı okur ve yenisini tercih eder, uygulama geçiş süresince ikisine de yazar, eldeki veri taşınır ve taşıma bittiğinde eski metafield kaldırılır.

Mantıklı bir iş sırası

1. Kuraldaki, işletmenin değiştirebileceği her değeri listeleyin: eşikler, listeler, mesajlar, tarihler.
2. Her birinin nerede duracağına karar verin: kural ayarları için sahip metafield’ı, başka yerde yönetilen veriler için ürün, müşteri ya da mağaza metafield’ları.
3. Her sahip için $app namespace’inde tek bir JSON şeması tanımlayın ve en baştan sürümleyin.
4. Her alanı doğrulayan bir yönetim paneli ayar ekranı kurun.
5. Bir geliştirme mağazasında kodu değil ayarları değiştirerek test edin ve ödeme sayfasının buna uyduğunu doğrulayın.

Lintel nereye uyar

Lintel, Shopify Functions çözümlerini, mağaza sahiplerinin en sık değiştirdiği ayarlar bir yönetim ekranıyla birlikte metafield’larda duracak şekilde tasarlar; Plus mağazalarında bunu bir özel uygulama içinde yapar. Değerleri koda gömülü bir Function’da bu değerleri metafield’lara taşımak, kapsamı belli bir iştir. Çoğu zaman işe doğrulamayla başlanır; bkz. ödeme sayfası doğrulamasının neleri engelleyebildiği.