Metafield tanımı oluşturma
metafieldDefinitionCreate ile tipli ve doğrulamalı bir metafield tanımı oluşturun, admin’de sabitleyin ve Storefront API’ye açın.
- API
- Admin GraphQL API
- İşlem
- metafieldDefinitionCreate
- Yerini aldığı REST çağrısı
- Yok; tanımlar yalnızca GraphQL ile yönetilir
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Bir metafield tanımı oluşturmak için metafieldDefinitionCreate’i name, namespace, key, ownerType ve type ile, isteğe bağlı olarak validations, access ve pin ile çağırın. Tanım, metafield’a sabit bir tip, Shopify admin’de bir düzenleme alanı ve izin verilen değerler listesi gibi kurallar kazandırır. Headless bir mağaza bu değeri Storefront API ile okuyacaksa access.storefront’u PUBLIC_READ yapın.
Nasıl kullanılır
- Sahip tipini (burada PRODUCT), bir namespace ve key’i, Shopify’ın metafield tiplerinden birini seçin.
- Gerekiyorsa doğrulama ekleyin; örneğin sabit bir değer listesi için choices. Doğrulama değerleri metindir, bu yüzden liste metin içinde bir JSON dizisi olarak yazılır.
- Headless bir mağaza değeri okuyacaksa access.storefront’u PUBLIC_READ, admin’de ürün sayfasında göstermek için pin: true yapın.
- CreateFabricDefinition’ı gönderin ve userErrors’ı kontrol edin; TAKEN, bu namespace ve key ile bir tanımın zaten olduğu anlamına gelir.
Kod
metafield-definition-create.graphqlmutation CreateFabricDefinition($definition: MetafieldDefinitionInput!) {
metafieldDefinitionCreate(definition: $definition) {
createdDefinition {
id
namespace
key
name
ownerType
type {
name
}
validations {
name
value
}
access {
storefront
}
}
userErrors {
code
field
message
}
}
}
metafield-definition-create.variables.json{
"definition": {
"name": "Fabric",
"namespace": "custom",
"key": "fabric",
"description": "Main fabric, shown on the product page and used as a filter.",
"ownerType": "PRODUCT",
"type": "single_line_text_field",
"validations": [
{
"name": "choices",
"value": "[\"Cotton\",\"Linen\",\"Wool\"]"
}
],
"access": {
"storefront": "PUBLIC_READ"
},
"pin": true
}
}
metafield-definition-create.response.json{
"data": {
"metafieldDefinitionCreate": {
"createdDefinition": {
"id": "gid://shopify/MetafieldDefinition/1234567890",
"namespace": "custom",
"key": "fabric",
"name": "Fabric",
"ownerType": "PRODUCT",
"type": {
"name": "single_line_text_field"
},
"validations": [
{
"name": "choices",
"value": "[\"Cotton\",\"Linen\",\"Wool\"]"
}
],
"access": {
"storefront": "PUBLIC_READ"
}
},
"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
- Aynı sahip tipi, namespace ve key’e sahip mevcut metafield’lar yeni tanıma göre kontrol edilir. Geçerli olanlar tanımın tipini alır; geçersiz olanlar değerini korur ama bir sonraki kayıtta tanıma uymak zorundadır.
- namespace’i boş bırakırsanız uygulamanıza ayrılmış namespace kullanılır; bu namespace’teki tanımlar uygulamanıza aittir.
- Bir tanımın tipi sonradan değiştirilemez; tip yanlışsa yeni bir key oluşturun.
- Sahip tipi başına sabitlenebilecek tanım sayısı sınırlıdır; userErrors’ta PINNED_LIMIT_REACHED görürseniz bu sınıra ulaşmışsınızdır.
Sık sorulan sorular
- Metafield ile metafield tanımı arasındaki fark nedir?
- Metafield tek bir kayıttaki değerdir. Tanım ise o tipteki tüm kayıtlar için namespace ve key’i tarif eder: tipini, doğrulamasını, admin’deki düzenleme alanını ve API erişimini.
- Metafield’ımı neden Storefront API ile okuyamıyorum?
- Tanımında storefront erişiminin PUBLIC_READ olması gerekir. NONE ise Storefront API değeri okuyamaz.
- Bir metafield’ı belirli değerlerle sınırlayabilir miyim?
- Evet. İzin verilen değerleri içeren bir JSON dizisiyle choices doğrulaması ekleyin; admin açılır liste gösterir, API de diğer değerleri reddeder.
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ı.
