metafieldsSet ile metafield yazma
Herhangi bir kayıtta en fazla 25 metafield’ı tek ve atomik bir çağrıyla oluşturun ya da güncelleyin; compareDigest ile yeni değerlerin üzerine yazmayın.
- API
- Admin GraphQL API
- İşlem
- metafieldsSet
- Erişim yetkisi
- Metafield’ın bağlı olduğu kayıt için yazma yetkisi (ürünler, müşteriler vb.)
- Yerini aldığı REST çağrısı
- POST /admin/api/products/{id}/metafields.json ve PUT /admin/api/metafields/{id}.json
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Metafield yazmak için metafieldsSet mutation’ını ownerId, namespace, key, type ve value içeren bir girdi listesiyle çağırın. Metafield yoksa oluşturur, varsa günceller. Tek çağrı, farklı sahiplere ait en fazla 25 metafield alır ve atomiktir: biri başarısız olursa hiçbiri kaydedilmez. Kayıtlı değer siz okuduktan sonra değişmediyse güncellemek için compareDigest gönderin.
Nasıl kullanılır
- Her değer için bir girdi hazırlayın: ownerId (metafield taşıyabilen herhangi bir kayıt), namespace, key, type ve value. Değer JSON, sayı ya da liste olsa da her zaman metin (string) olarak gönderilir.
- Bu namespace ve key için bir metafield tanımı varsa type’ı atlayabilirsiniz; yoksa zorunludur.
- SetProductMetafields’ı gönderin ve userErrors’ı kontrol edin; boş değilse hiçbir şey kaydedilmemiştir.
- Güvenli güncelleme için önce compareDigest’i okuyup geri gönderin. compareDigest: null, yalnızca metafield henüz yoksa yazar.
Kod
metafields-set.graphqlmutation SetProductMetafields($metafields: [MetafieldsSetInput!]!) {
metafieldsSet(metafields: $metafields) {
metafields {
id
namespace
key
type
value
compareDigest
}
userErrors {
code
field
message
}
}
}
metafields-set.variables.json{
"metafields": [
{
"ownerId": "gid://shopify/Product/1234567890",
"namespace": "custom",
"key": "material",
"type": "single_line_text_field",
"value": "100% linen"
},
{
"ownerId": "gid://shopify/Product/1234567890",
"namespace": "custom",
"key": "care_guide",
"type": "multi_line_text_field",
"value": "Wash at 30°C.\nDo not tumble dry.",
"compareDigest": null
}
]
}
metafields-set.response.json{
"data": {
"metafieldsSet": {
"metafields": [
{
"id": "gid://shopify/Metafield/1111111111",
"namespace": "custom",
"key": "material",
"type": "single_line_text_field",
"value": "100% linen",
"compareDigest": "<digest from the response>"
},
{
"id": "gid://shopify/Metafield/1111111112",
"namespace": "custom",
"key": "care_guide",
"type": "multi_line_text_field",
"value": "Wash at 30°C.\nDo not tumble dry.",
"compareDigest": "<digest from the response>"
}
],
"userErrors": []
}
}
}
Lintel tarafından yazıldı. MIT lisansı: kendi mağazanızda da müşteri işlerinizde de ücretsiz kullanabilirsiniz.
Sınırlar ve özel durumlar
- Çağrı başına en fazla 25 metafield ve 10 MB istek boyutu.
- namespace’i boş bırakırsanız custom değil, uygulamanıza ayrılmış namespace kullanılır.
- Değerler tipe uymalıdır: liste tipleri metin içinde bir JSON dizisi, referanslar GID bekler; biri ayrıştırılamazsa istek başarısız olur.
- Bir metafield’ı silmek için metafieldsDelete mutation’ını kullanın.
Sık sorulan sorular
- Bir ürün metafield’ını GraphQL ile nasıl güncellerim?
- metafieldsSet’i ürünün GID’si ownerId olacak şekilde namespace, key, type ve yeni değerle çağırın. Mevcut metafield yerinde güncellenir.
- Tek çağrıda farklı ürünlere metafield yazabilir miyim?
- Evet. Her girdinin kendi ownerId’si vardır; tek çağrıyla birçok kayda toplam 25 metafield yazabilirsiniz.
- compareDigest ne işe yarar?
- Siz okuduktan sonra başkasının değiştirdiği bir değerin üzerine yazmanızı engeller. Kayıtlı değer digest ile artık eşleşmiyorsa mutation kaydetmek yerine hata döner.
Shopify belgeleri
- Gösterilen tarihte, 2026-10 sürümünün Admin veya Storefront API şemasıyla doğrulandı. İstek adresinizdeki sürümü kontrol edin.
- Örneklerdeki ID’ler ve mağaza adresleri yer tutucudur. Kendi değerlerinizle değiştirin.
- Admin API çağrıları uygulamanızdan bir erişim anahtarı (access token) ister. Admin API anahtarını asla vitrine ya da temaya koymayın.
- MIT lisansı. Kodu kendi mağazanızda da müşteri işlerinizde de kullanabilirsiniz.
Mağazanız için kurulmasını, test edilmesini ve bakımını isterseniz: API entegrasyonları.
