Storefront API ile metafield ve metaobject okuma
Bir ürünün metafield’larını okuyun, beden tablosu gibi bir metaobject referansını takip edin ve SSS gibi bir tipteki tüm metaobject’leri listeleyin.
- API
- Storefront API
- İşlemler
- product.metafield, metaobjects
- Erişim yetkileri
- unauthenticated_read_product_listings, unauthenticated_read_metaobjects
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Headless bir mağazada özel verileri okumak için tekil değerlerde product.metafield(namespace, key) seçin; bir metaobject referansını takip etmek için reference içinde Metaobject’e inline fragment kullanın. Bir tipteki tüm kayıtları, örneğin SSS’leri listelemek için metaobjects(type: "faq") sorgulayın. İkisi de yalnızca tanımında storefront erişimi PUBLIC_READ olan verileri döndürür.
Nasıl kullanılır
- Metafield ve metaobject tanımlarının storefront erişiminin PUBLIC_READ olduğundan emin olun.
- ProductCustomData’yı gönderin; alias’lar (fabric, sizeChart) tek sorguda birkaç metafield okumanızı sağlar.
- Bir referans için reference { ... on Metaobject { … } } seçin ve alanları key’e göre alın.
- Bir tipteki kayıtları listelemek için StoreFaq’ı gönderin ve hasNextPage true olduğu sürece after ile sayfalayın.
Kod
product-custom-data.graphqlquery ProductCustomData($handle: String!) {
product(handle: $handle) {
title
fabric: metafield(namespace: "custom", key: "fabric") {
value
}
sizeChart: metafield(namespace: "custom", key: "size_chart") {
reference {
... on Metaobject {
handle
title: field(key: "title") {
value
}
rows: field(key: "rows") {
value
}
}
}
}
}
}
product-custom-data.variables.json{
"handle": "linen-shirt"
}
product-custom-data.response.json{
"data": {
"product": {
"title": "Linen shirt",
"fabric": {
"value": "Linen"
},
"sizeChart": {
"reference": {
"handle": "shirts",
"title": {"value": "Shirts"},
"rows": {"value": "[{\"size\":\"S\",\"chest\":96},{\"size\":\"M\",\"chest\":102},{\"size\":\"L\",\"chest\":108}]"}
}
}
}
}
}
metaobjects-by-type.graphqlquery StoreFaq($type: String!, $first: Int!) {
metaobjects(type: $type, first: $first) {
nodes {
handle
fields {
key
value
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
metaobjects-by-type.variables.json{
"type": "faq",
"first": 20
}
metaobjects-by-type.response.json{
"data": {
"metaobjects": {
"nodes": [
{
"handle": "shipping-time",
"fields": [
{"key": "question", "value": "How long does shipping take?"},
{"key": "answer", "value": "Two to four working days within the EU."}
]
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "eyJsYXN0X2lkIjoxMTExMTExMTExfQ=="
}
}
}
}
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
- Storefront erişimi olmayan bir metafield, hiç yokmuş gibi null döner.
- Alias kullanmadan birkaç metafield okumak için metafields(identifiers: [{namespace, key}, …]) kullanın.
- Değerler metindir; json ve liste tiplerini kendiniz ayrıştırın.
- Tek bir kaydı handle ile okumak için metaobject(handle: {type, handle}) kullanın; handle’lar yalnızca bir tip içinde benzersizdir.
Sık sorulan sorular
- Storefront API ile ürün metafield’ları nasıl alınır?
- Üründe metafield(namespace: "custom", key: "anahtariniz") { value } seçin. Metafield tanımının storefront erişimi PUBLIC_READ olmalıdır.
- Hydrogen’da metaobject’ler nasıl sorgulanır?
- Tiple birlikte metaobjects sorgusunu kullanın ya da bir ürün metafield’ındaki metaobject referansını takip edin. Hydrogen’ın storefront istemcisi aynı Storefront API sorgularını çalıştırır.
- Metafield’ım Storefront API’de neden null dönüyor?
- Genellikle tanımı storefront erişimine izin vermiyordur ya da namespace veya key farklıdır. Tanımda storefront erişimini PUBLIC_READ yapın.
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ı.
