Zenn
📈

【Shopify.dev和訳】 AdminAPI/GraphQL reference/Metafields

2021/10/01に公開
GraphQL
API
Shopify
tech

この記事について

この記事は、Admin API/GraphQL reference/Metafields APIsの記事を和訳したものです。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Metafields APIs

Metafields API とはオブジェクトのパブリックおよびプライベートのメタフィールドを管理する API です。

Overview

  • HasMetafields - 指定されたリソースに関連付けられたメタフィールドに関する情報を表します。

  • Metafield - メタフィールドは、リソースに関連付けられたカスタムメタデータを表します。メタフィールドは名前空間にソートすることができ、キー、値、および値のタイプで構成されます。

  • MetafieldDefinition - メタフィールドの定義により、マーチャントは管理者用リソースページから表示・管理されるメタフィールドのセットを構成することができます。

  • MetafieldDeleteInput - メタフィールドを削除するための入力フィールドを指定します。

  • MetafieldInput - メタフィールドの入力フィールドを指定します。

  • MetafieldOwnerType - メタフィールドのオーナーリソースのタイプを指定します。

  • MetafieldReference - メタフィールドが参照しているリソースを返します。

  • MetafieldStorefrontVisibility - メタフィールドをストアフロントに表示するための許可リストレコードを表します。

  • MetafieldStorefrontVisibilityInput - ストアフロントに表示するための入力フィールドを指定します。

  • MetafieldValidationStatus - メタフィールドの Validation ステータスです。

  • MetafieldValueType - メタフィールドの値の種類です。

  • MetafieldsSetInput - メタフィールドの値を設定する入力フィールドを指定します。

  • PrivateMetafield - プライベート メタフィールドは、リソースに添付されるカスタム メタデータを表します。プライベートメタフィールドは、ショップのリソース上に作成されたアプリケーションに対してプライベートなものです。

  • PrivateMetafieldDeleteInput - プライベート メタフィールドの入力フィールドを指定します。

  • PrivateMetafieldInput - プライベートメタフィールドの入力フィールドを指定します。

  • PrivateMetafieldValueInput - Value Input はプライベートメタフィールドの 2 つのフィールドを 1 つにまとめます。それらのフィールドは value と value_type です。

  • PrivateMetafieldValueType - プライベートメタフィールドの値の種類です。

  • metafieldDelete - メタフィールドを削除します。

  • metafieldStorefrontVisibilityCreate - 特定の名前空間とキーを持つメタフィールドをストアフロント API から見えるようにします。

  • metafieldStorefrontVisibilityDelete - メタフィールドのストアフロントの可視性を削除します。

  • metafieldsSet - メタフィールドの値を設定します。メタフィールドの値は、以前に作成されたかどうかに関係なく設定されます。一度に最大 25 個のメタフィールドを設定することができます。

  • privateMetafieldDelete - プライベートのメタフィールドを削除します。

  • privateMetafieldUpsert - プライベートメタフィールドの作成または更新を行います。

UNIONS

MetafieldReference(union)

メタフィールドで参照されているリソースを返します。

利用可能なタイプ

OBJECTS

Metafield(object)

メタフィールドは、リソースに付けられたカスタムメタデータを表します。メタフィールドは、名前空間でソートすることができ、キー、値、および値のタイプで構成されます。

Fields

createdAt (DateTime!)
メタフィールドが作成された日付と時間。

description (String)
メタフィールドの説明です。

id (ID!)
グローバルに一意な識別子。

key (String!)
メタフィールドのキー名。

legacyResourceId (UnsignedInt64!)
REST Admin API の対応するリソースの ID。

namespace (String!)
メタフィールドの名前空間。

ownerType (MetafieldOwnerType!)
Storefront API で見えるメタフィールドのオーナー・タイプ。

type (String!)
メタフィールドのタイプ名です。サポートされるタイプのリストを参照してください。

updatedAt (DateTime!)
メタフィールドが更新された日付と時間。

value (String!)
メタフィールドの値です。

Metafield の返すタイプ

Metafield のミューテーション

metafieldDelete
メタフィールを削除する

Implements

廃止された fields

Samples

query
# productの最初の 10 metafieldsを取得するquery
{
  product(id:"gid://shopify/Product/1974208397334") {
    metafields(first: 10) {
      edges {
        node {
          id
          value
          valueType
          description
          legacyResourceId
        }
      }
    }
  }
}
response
{
  "data": {
    "product": {
      "metafields": {
        "edges": []
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 13,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 997,
        "restoreRate": 50
      }
    }
  }
}

MetafieldDefinition(object)

MetafieldDefinition は、マーチャントが管理者用リソースページから表示・管理されるメタフィールドのセットを設定することができます。

Connections

metafields (MetafieldConnection!)
定義の関連するメタフィールドのリスト。

引数 説明
after ( String ) 指定されたカーソルの後に来る要素を返します。
before ( String ) 指定されたカーソルより前にある要素を返します。
first ( Int ) リストから最初の n 個の要素までを返します。
last ( Int ) リストから最後の n 個の要素までを返します。
reverse ( Boolean ) 対象となるリストの順序を逆にします。
デフォルト値：false
validationStatus ( MetafieldValidationStatus ) メタフィールドの validation ステータスでフィルタリングします。
デフォルトの値は ANY

Fields

description (String)
メタフィールドの定義の説明です。

id (ID!)
グローバルに一意な識別子。

key (String!)
メタフィールド定義のキー名。

metafieldsCount (Int!)
メタフィールド定義の下にあるメタフィールドの数。

引数 説明
validationStatus ( MetafieldValidationStatus ) メタフィールドの検証状況。

name (String!)
メタフィールドの定義の名前です。

namespace (String!)
メタフィールド定義の名前空間です。

ownerType (MetafieldOwnerType!)
定義が適用されるリソースタイプです。

pinnedPosition (Int)
ピン留めリストにおける定義の位置。

presentation (JSON!)
定義に関連するプレゼンテーションオプション。

standardTemplate (StandardMetafieldDefinitionTemplate)
定義に関連する標準的なメタフィールド定義テンプレート（利用可能な場合）。

type (MetafieldDefinitionType!)
関連するメタフィールド定義タイプ。

validationStatus (MetafieldDefinitionValidationStatus!)
メタフィールド定義の検証状況です。

validations ([MetafieldDefinitionValidation!]!)
定義に関連する検証オプション。

MetafieldDefinitionの返すタイプ

MetafieldDefinition の Mutation

metafieldDefinitionCreate
メタフィールド定義を作成します。

metafieldDefinitionDelete
メタフィールド定義を削除します。指定されている場合は、関連するすべてのメタフィールドを非同期に削除します。

metafieldDefinitionPin
メタフィールド定義をピン留めします。

metafieldDefinitionUnpin
メタフィールド定義をアンピンします。

metafieldDefinitionUpdate
メタフィールド定義を更新します。

Implements

MetafieldStorefrontVisibility(object)

メタフィールドをストアフロントで表示できるようにする allowlist レコードを表します。

Fields

createdAt (DateTime!)
許可リストのレコードが作成された日時です。

id (ID!)
グローバルに一意な識別子です。

key (String!)
可視性許可リストのメタフィールドのキー。

legacyResourceId (UnsignedInt64!)
REST Admin API 内の対応するリソースの ID。

namespace (String!)
可視性許可リスト内のメタフィールドの名前空間。

ownerType (MetafieldOwnerType!)
可視性許可リスト内のメタフィールドの所有者タイプ。

updatedAt (DateTime!)
許可リストのレコードが更新された日付と時間。

MetafieldStorefrontVisibilityの返すタイプ

MetafieldStorefrontVisibilityの Mutation

metafieldStorefrontVisibilityCreate
特定のネームスペースとキーを持つメタフィールドをストアフロント API から見えるようにします。

metafieldStorefrontVisibilityDelete
Metafield Storefront Visibility を削除します。

Implements

Samples

query
# メタフィールドをストアフロントで表示できるようにする allowlist レコードのうち、最初の 10 個の ID を取得します。
{
  metafieldStorefrontVisibilities(first:10) {
    edges {
      node {
        id
      }
    }
  }
}
response
{
  "data": {
    "metafieldStorefrontVisibilities": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/229398"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/262166"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/983062"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/126648342"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/127074326"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/127696918"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/127729686"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/127762454"
          }
        },
        {
          "node": {
            "id": "gid://shopify/MetafieldStorefrontVisibility/127860758"
          }
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 11,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 989,
        "restoreRate": 50
      }
    }
  }
}

PrivateMetafield(object)

プライベート メタフィールドは、リソースに付加されるカスタム メタデータを表します。プライベート・メタフィールドは、ショップのリソース上に作成したアプリケーションに対してプライベートなものです。

Fields

createdAt (DateTime!)
プライベートのメタフィールドが作成された日時です。

id (ID!)
プライベートメタフィールドの id です。

key (String!)
プライベート・メタフィールドのキー名です。

namespace (String!)
プライベート・メタフィールドの名前空間。

updatedAt (DateTime!)
プライベート・メタフィールドが更新された日付と時間。

value (String!)
プライベート・メタフィールドの値です。

valueType (PrivateMetafieldValueType!)
プライベート・メタフィールドの値のタイプを表します。

PrivateMetafieldの返すタイプ

PrivateMetafield の Mutations

privateMetafieldDelete
プライベート・メタフィールドを削除します。

privateMetafieldUpsert
プライベート・メタフィールドを作成または更新します。

Implements

Samples

query
# リソースの最初の10個のプライベート・メタフィールドを問い合わせる
{
  product(id:"gid://shopify/Product/10079785100") {
    privateMetafields(first:10) {
      edges {
        node {
          id
          namespace
          key
          value
          valueType
        }
      }
    }
  }
}
response
{
  "data": {
    "product": null
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 13,
      "actualQueryCost": 1,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 999,
        "restoreRate": 50
      }
    }
  }
}

MUTATIONS

metafieldDelete(mutation)

メタフィールドを削除する

例

mutation query の実行例です。

query
mutation metafieldDelete($input: MetafieldDeleteInput!) {
  metafieldDelete(input: $input) {
    deletedId
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "input": {
    "id": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE="
  }
}

引数

引数 説明
input ( MetafieldDeleteInput! ) required

MetafieldDeleteInput fields

id (ID!) required
削除するメタフィールドの ID です。

Return fields

deletedId (ID)
削除されたメタフィールドの ID です。

userErrors ([UserError!]!)
Mutation を実行して発生したエラーのリストです。

metafieldsSet(mutation)

一度に最大 25 個のメタフィールドを設定することができます。

Interactive example

query
mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
    }
    userErrors {
      code
      field
      message
    }
  }
}
Variables
{
  "metafields": [
    {
      "ownerId": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE=",
      "namespace": "placeholder",
      "key": "placeholder",
      "value": "placeholder",
      "type": "placeholder"
    }
  ]
}

Arguments

引数 説明
metafields ( [MetafieldsSetInput!]! required) 設定するメタフィールド値のリスト。最大 25 個まで設定可能。

MetafieldsSetInput fields

key (String!) required
メタフィールドのキー名です。

namespace (String!) required
メタフィールドの名前空間です。

ownerId (ID!) required
オーナーリソースの ID です。

type (String!) required
メタフィールドの型名です。サポートされているタイプでなければなりません。

value (String!) required
メタフィールドの値を指定します。

Return fields

metafields ([Metafield!])
設定されたメタフィールドのリストです。

userErrors ([MetafieldsSetUserError!]!)
Mutation を実行する際に発生したエラーのリスト。

metafieldStorefrontVisibilityCreate(mutation)

特定のネームスペースとキーを持つメタフィールドを、ストアフロント API で表示できるようにします。

例

query
mutation metafieldStorefrontVisibilityCreate($input: MetafieldStorefrontVisibilityInput!) {
  metafieldStorefrontVisibilityCreate(input: $input) {
    metafieldStorefrontVisibility {
      id
    }
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "input": {
    "namespace": "placeholder",
    "key": "placeholder",
    "ownerType": "placeholder"
  }
}

引数

Argument Description
input ( MetafieldStorefrontVisibilityInput! ) required 可視性の入力フィールドを指定します。

MetafieldStorefrontVisibilityInput fields

key（ String! ） required
ストアフロント API に表示するメタフィールドのキーです。

namespace ( String! ) required
ストアフロントの API で表示されるメタフィールドの名前空間です。

ownerType ( MetafieldOwnerType! ) required
このメタフィールドを所有するコアリソース（例：Product）。

Return fields

metafieldStorefrontVisibility（ MetafieldStorefrontVisibility)
作成されたメタフィールドのストアフロントの可視性です。

userErrors ( [UserError!]! )
mutation を実行して発生したエラーのリストです。

metafieldStorefrontVisibilityDelete(mutation)

Metafield Storefront Visibility を削除します。

例

query
mutation metafieldStorefrontVisibilityDelete($id: ID!) {
  metafieldStorefrontVisibilityDelete(id: $id) {
    deletedMetafieldStorefrontVisibilityId
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "id": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE="
}

引数

引数 説明
id ( ID! ) required 削除するメタフィールドのストアフロントの可視性の ID です。

Return fields

deletedMetafieldStorefrontVisibilityId ( ID )
削除されたメタフィールド・ストアフロント・ビジビリティの ID です。

userErrors ( [UserError!]! )
Mutation を実行して発生したエラーのリストです。

privateMetafieldDelete(mutation)

プライベートメタフィールドを削除します。

例

query
mutation privateMetafieldDelete($input: PrivateMetafieldDeleteInput!) {
  privateMetafieldDelete(input: $input) {
    deletedPrivateMetafieldId
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "input": {
    "namespace": "placeholder",
    "key": "placeholder"
  }
}

引数

引数 説明
input ( PrivateMetafieldDeleteInput! ) required プライベート メタフィールドの入力フィールドを指定します。

PrivateMetafieldDeleteInput fields

key ( String! ) required
プライベートメタフィールドのキーです。

namespace ( String! ) required
プライベート・メタフィールドの名前空間です。

owner ( ID )
所有しているリソースの ID。

Return fields

deletedPrivateMetafieldId ( ID )
削除されたプライベートメタフィールドの ID です。

userErrors ( [UserError!]! )
Mutation を実行して発生したエラーのリストです。

privateMetafieldUpsert(mutation)

プライベートのメタフィールドを作成または更新します。

例

query
mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
  privateMetafieldUpsert(input: $input) {
    privateMetafield {
      id
    }
    userErrors {
      field
      message
    }
  }
}
Variables
{
  "input": {
    "namespace": "placeholder",
    "key": "placeholder",
    "valueInput": {
      "value": "placeholder",
      "valueType": "placeholder"
    }
  }
}

引数

引数 説明
input ( PrivateMetafieldInput! ) required プライベート・メタフィールドの入力フィールドを指定します。

PrivateMetafieldInput fields

key ( String! ) required
プライベートメタフィールドのキーです。

namespace ( String! ) required
プライベート・メタフィールドの名前空間です。

owner ( ID )
所有するリソースです。

valueInput ( PrivateMetafieldValueInput! ) required
ValueInput オブジェクトでラップされた、メタフィールドの値と値のタイプ。

Return fields

privateMetafield ( PrivateMetafield )
作成または更新されたプライベートメタフィールドです。

userErrors ( [UserError!]! )
Mutation を実行して発生したエラーのリストです。

INTERFACES

HasMetafields(interface)

指定されたリソースに関連するメタフィールドの情報を表します。

Fields

metafield（ Metafield )
リソースに属している名前空間とキーによるメタフィールドを返します。

引数 説明
key ( String! ) required メタフィールドのキーです。
namespace ( String! ) required メタフィールドの名前空間。

metafields ( MetafieldConnection! )
リソースに属するメタフィールドのリスト。

引数 説明
after ( String ) 指定したカーソルの後にある要素を返します。
before ( String ) 指定されたカーソルの前にある要素を返す。
first ( Int ) リストから最初の n 個の要素までを返します。
last ( Int ) リストから最後の n 個の要素までを返します。
namespace ( String ) フィルタリングするメタフィールドの名前空間です。
reverse ( Boolean ) 対象となるリストの順序を逆にします。
デフォルト値：false

privateMetafield ( PrivateMetafieldConnection! )
リソースに属する、名前空間とキーによるプライベートメタフィールドを返します。

引数 説明
key ( String! ) required プライベート・メタフィールドのキーです。
namespace ( String! ) required プライベート メタフィールドのための名前空間。

privateMetafields ( PrivateMetafieldConnection! )
リソースに属するプライベートメタフィールドのリスト。

引数 説明
after ( String ) 指定されたカーソルの後に来る要素を返します。
before ( String ) 指定されたカーソルの前にある要素を返す。
first ( Int ) リストから最初の n 個の要素までを返します。
last ( Int ) リストから最後の n 個の要素までを返します。
namespace ( String ) プライベート メタフィールドを名前空間でフィルタリングします。
reverse ( Boolean ) 基礎となるリストの順序を逆にします。
デフォルト値：false

HasMetafields implment のタイプ

INPUTS

MetafieldDeleteInput(input object)

メタフィールドを削除するための入力フィールドを指定します。

Input fields

id ( ID! ) required
削除するメタフィールドの ID です。

MetafieldInput(input object)

メタフィールドの入力フィールドを指定します。

Input fields

description ( String )
メタフィールドの説明です。

id ( ID )
メタフィールドのユニークな ID です。

key ( String )
メタフィールドのキー名です。

namespace ( String )
メタフィールドの名前空間です。

type ( String )
メタフィールドの型名。サポートされている型でなければなりません。

value ( String )
メタフィールドの値を指定します。

MetafieldsSetInput(input object)

メタフィールドの値を設定するための入力フィールドを指定します。

Input fields

key（ String!) required
メタフィールドのキー名です。

namespace ( String! ) required
メタフィールドの名前空間です。

ownerId ( ID! ) required
オーナーリソースの ID です。

type ( String! ) required
メタフィールドの型名です。サポートされているタイプでなければなりません。

value ( String! ) required
メタフィールドの値を指定します。

MetafieldStorefrontVisibilityInput(input object)

MetafieldStorefrontVisibilityInput の入力フィールドを指定します。

Input fields

key（ String! ） required
ストアフロント API に表示するメタフィールドのキーです。

namespace ( String! ) required
ストアフロントの API で表示されるメタフィールドの名前空間です。

ownerType ( MetafieldOwnerType! ) required
このメタフィールドを所有するコアリソース（例：Product）。

PrivateMetafieldDeleteInput(input object)

PrivateMetafield の入力フィールドを指定します。

Input fields

key ( String! ) required
プライベートメタフィールドのキーです。

namespace ( String! ) required
プライベート・メタフィールドの名前空間です。

owner ( ID )
所有しているリソースの ID。

PrivateMetafieldInput(input object)

PrivateMetafield の入力フィールドを指定します。

Input fields

key ( String! ) required
プライベートメタフィールドのキーです。

namespace ( String! ) required
プライベート・メタフィールドの名前空間です。

owner ( ID )
所有するリソースです。

valueInput ( PrivateMetafieldValueInput!) required
ValueInputオブジェクトでラップされた、メタフィールドの値と値のタイプ。

PrivateMetafieldValueInput(input object)

Value Input は Private Metafields の 2 つのフィールドを 1 つにまとめます。それらのフィールドは value と value_type です。

Input fields

value ( String! ) required
プライベート・メタフィールドの値です。

valueType ( PrivateMetafieldValueType! ) required
プライベート・メタフィールドの値のタイプを表します。

ENUMS

MetafieldOwnerType(enum)

メタフィールドのオーナーリソースの種類を指定します。

Values

ARTICLE
記事のメタフィールドのオーナータイプ。

BLOG
ブログのメタフィールドのオーナータイプ。

COLLECTION
コレクションのメタフィールドの所有者タイプ。

CUSTOMER
顧客のメタフィールドのオーナー・タイプ。

DRAFTORDER
下書き注文のメタフィールド・オーナー・タイプ。

ORDER
注文メタフィールドの所有者タイプ。

PAGE
ページのメタフィールドのオーナータイプ。

PRODUCT
Productメタフィールドのオーナータイプ。

PRODUCTIMAGE
製品イメージのメタフィールドのオーナータイプ。

PRODUCTVARIANT
商品バリエーションのメタフィールドのオーナータイプ。

SHOP
ショップのメタフィールドのオーナータイプ。

MetafieldOwnerType を返す型

MetafieldValidationStatus(enum)

可能なメタフィールドの検証ステータス。

Values

ANY
任意の検証ステータス（有効または無効）。

INVALID
定義に基づき無効。

VALID
定義に基づいて有効。

MetafieldValueType(enum)

メタフィールドの値の種類

Values

BOOLEAN
メタフィールドの真偽値。

INTEGER
整数

JSON_STRING
JSON の文字列。

STRING
文字列

PrivateMetafieldValueType(enum)

プライベートメタフィールドの値の種類

Values

INTEGER
整数のメタフィールドです。

JSON_STRING
JSON 文字列のメタフィールド。

STRING
文字列のメタフィールド。

PrivateMetafieldValueTypeの返す種類

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます