Metaobject tanımı oluşturma ve kayıtları upsert etme
Beden tablosunu metaobject olarak kurun: tanımı metaobjectDefinitionCreate ile oluşturun, kayıtları handle’a göre metaobjectUpsert ile ekleyip güncelleyin.
- API
- Admin GraphQL API
- İşlemler
- metaobjectDefinitionCreate, metaobjectUpsert
- Erişim yetkileri
- write_metaobject_definitions, write_metaobjects
- Yerini aldığı REST çağrısı
- Yok; metaobject’ler yalnızca GraphQL ile yönetilir
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Beden tablosu ya da SSS gibi yapılandırılmış içerikleri saklamak için metaobjectDefinitionCreate ile bir metaobject tanımı (type, alanlar, erişim, yetenekler) oluşturun, ardından kayıtları metaobjectUpsert ile yazın. Upsert, kaydı type ve handle ile bulur: varsa günceller, yoksa oluşturur; böylece aynı içe aktarımı güvenle tekrar çalıştırabilirsiniz. Kaydı göstermek için ona bir ürün metafield’ından referans verin.
Nasıl kullanılır
- CreateSizeChartDefinition’ı her mağaza için bir kez gönderin. displayNameKey, admin’de kaydın adı olarak gösterilecek alanı seçer.
- Kayıtların taslak ve aktif durumu olsun istiyorsanız publishable yeteneğini açın; headless mağazalar için storefront erişimini PUBLIC_READ yapın.
- Her tablo için UpsertSizeChart’ı type ve handle ile gönderin. Alan değerleri metindir; json alanı bir JSON metni alır.
- Tabloyu ürünlere metaobject_reference tipinde bir metafield ile bağlayın, ardından Liquid’de ya da Storefront API ile okuyun.
Kod
metaobject-definition-create.graphqlmutation CreateSizeChartDefinition($definition: MetaobjectDefinitionCreateInput!) {
metaobjectDefinitionCreate(definition: $definition) {
metaobjectDefinition {
id
type
name
displayNameKey
fieldDefinitions {
key
name
required
type {
name
}
}
}
userErrors {
code
field
message
}
}
}
metaobject-definition-create.variables.json{
"definition": {
"name": "Size chart",
"type": "size_chart",
"displayNameKey": "title",
"access": {
"storefront": "PUBLIC_READ"
},
"capabilities": {
"publishable": {
"enabled": true
}
},
"fieldDefinitions": [
{"key": "title", "name": "Title", "type": "single_line_text_field", "required": true},
{
"key": "unit",
"name": "Unit",
"type": "single_line_text_field",
"validations": [{"name": "choices", "value": "[\"cm\",\"in\"]"}]
},
{"key": "rows", "name": "Rows", "type": "json", "required": true}
]
}
}
metaobject-definition-create.response.json{
"data": {
"metaobjectDefinitionCreate": {
"metaobjectDefinition": {
"id": "gid://shopify/MetaobjectDefinition/1234567890",
"type": "size_chart",
"name": "Size chart",
"displayNameKey": "title",
"fieldDefinitions": [
{"key": "title", "name": "Title", "required": true, "type": {"name": "single_line_text_field"}},
{"key": "unit", "name": "Unit", "required": false, "type": {"name": "single_line_text_field"}},
{"key": "rows", "name": "Rows", "required": true, "type": {"name": "json"}}
]
},
"userErrors": []
}
}
}
metaobject-upsert.graphqlmutation UpsertSizeChart($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
metaobject {
id
handle
displayName
capabilities {
publishable {
status
}
}
fields {
key
value
}
}
userErrors {
code
field
message
}
}
}
metaobject-upsert.variables.json{
"handle": {
"type": "size_chart",
"handle": "shirts"
},
"metaobject": {
"fields": [
{"key": "title", "value": "Shirts"},
{"key": "unit", "value": "cm"},
{"key": "rows", "value": "[{\"size\":\"S\",\"chest\":96},{\"size\":\"M\",\"chest\":102},{\"size\":\"L\",\"chest\":108}]"}
],
"capabilities": {
"publishable": {
"status": "ACTIVE"
}
}
}
}
metaobject-upsert.response.json{
"data": {
"metaobjectUpsert": {
"metaobject": {
"id": "gid://shopify/Metaobject/1234567890",
"handle": "shirts",
"displayName": "Shirts",
"capabilities": {
"publishable": {
"status": "ACTIVE"
}
},
"fields": [
{"key": "title", "value": "Shirts"},
{"key": "unit", "value": "cm"},
{"key": "rows", "value": "[{\"size\":\"S\",\"chest\":96},{\"size\":\"M\",\"chest\":102},{\"size\":\"L\",\"chest\":108}]"}
]
},
"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
- type oluşturulduktan sonra değiştirilemez. Uygulamanıza ayırmak için başına $app: ekleyin.
- publishable açıkken bir kayıt, yalnızca durumu ACTIVE ise mağazada görünür.
- Güncellemede gönderdiğiniz değerler kayıtlı olanların üzerine yazılır.
- metaobjects/create, update ve delete webhook’ları, type:size_chart gibi tipi belirten bir filtre ister.
Sık sorulan sorular
- Metafield ile metaobject arasındaki fark nedir?
- Metafield, mevcut bir kayda tek bir değer ekler. Metaobject ise birden fazla alanı olan, kendi başına bir kayıttır; beden tablosu ya da SSS maddesi gibi, birçok ürün ona referans verebilir.
- ID’sini bilmeden bir metaobject’i nasıl güncellerim?
- metaobjectUpsert’i type ve handle ile kullanın. Handle varsa kaydı günceller, yoksa yenisini oluşturur.
- Metaobject’im neden mağazada görünmüyor?
- Tanımın storefront erişiminin PUBLIC_READ olduğunu ve publishable açıksa kaydın durumunun ACTIVE olduğunu kontrol edin.
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ı.
