ポイントとか、こんな私がいうのも烏滸がましいのですが、GraphQLでShopifyのデータ取得する際に管理画面とのマッピング、それとページネーションにえれー苦労したので、備忘録です。

今回は、顧客情報(Customer)です。

Shopify GraphQLのCustomerドキュメントは、以下を参照してください。
現在この記事を書いている時点の最新バージョンは2024/10です。
Shopify GraphQLのバージョンは年に4回更新されますので、以下のページだけでなく、最新のバージョンのページでも確認してください。

Shopify Partnersになると、"Quickstart"というテスト用のショップを用意してくれます。
今回はこのショップを使っていきます。

管理画面で見る顧客情報

管理画面では、こんな感じに顧客情報が展開されています。

また、一人ひとりの顧客情報は、顧客名をクリックすると、詳細ページに行けます。

詳細ページの右側にある、「お客様」という枠が、顧客情報(Customer)になります。
GraphQLでは、「直近の注文」も顧客情報のGraphQLから取得できますが、この記事では、純粋にお客さま情報を取得します。

まずは、Postmanで

Postmanで実行してみましょう。

query {
customers( first: 250, query: "updated_at:>2024-01-01T00:00:00Z") {
    edges {
      node {
        id
        firstName
        lastName
        displayName
        phone
        email
        updatedAt
        defaultAddress{
            phone
            address1
            address2
            country
            city
            zip
            firstName
            lastName
            company
        }
      }
    }
  }
}

件数は特に指定していませんが、ここでは、2024/01/01以降に更新(登録)された顧客情報を取得しています。
全件取得したい時は、ショップを立ち上げた日を指定するといいと思います。

結果は、以下のように返ってきます。

{
    "data": {
        "customers": {
            "edges": [
                {
                    "node": {
                        "id": "gid://shopify/Customer/7560854569210",
                        "firstName": "Karine",
                        "lastName": "Ruby",
                        "displayName": "Karine Ruby",
                        "phone": "+16135550142",
                        "email": "karine.ruby@example.com",
                        "updatedAt": "2024-08-28T09:29:51Z",
                        "defaultAddress": null
                    }
                },
                {
                    "node": {
                        "id": "gid://shopify/Customer/7560854601978",
                        "firstName": "Russell",
                        "lastName": "Winfield",
                        "displayName": "Russell Winfield",
                        "phone": "+16135550135",
                        "email": "russel.winfield@example.com",
                        "updatedAt": "2024-08-28T09:29:51Z",
                        "defaultAddress": {
                            "phone": null,
                            "address1": "105 Victoria St",
                            "address2": null,
                            "country": "Canada",
                            "city": "Toronto",
                            "zip": "M5C1N7",
                            "firstName": "Russell",
                            "lastName": "Winfield",
                            "company": "Company Name"
                        }
                    }
                },
                {
                    "node": {
                        "id": "gid://shopify/Customer/7560854634746",
                        "firstName": "Ayumu",
                        "lastName": "Hirano",
                        "displayName": "Ayumu Hirano",
                        "phone": "+16135550127",
                        "email": "ayumu.hirano@example.com",
                        "updatedAt": "2024-08-28T09:29:51Z",
                        "defaultAddress": null
                    }
                }
            ]
        }
    },
    "extensions": {
        "cost": {
            "requestedQueryCost": 13,
            "actualQueryCost": 4,
            "throttleStatus": {
                "maximumAvailable": 2000.0,
                "currentlyAvailable": 1996,
                "restoreRate": 100.0
            }
        },
        "search": [
            {
                "path": [
                    "customers"
                ],
                "query": "updated_at:>2024-01-01T00:00:00Z",
                "parsed": {
                    "and": [
                        {
                            "field": "updated_at",
                            "range_gte": "2024-01-01T00:00:00-05:00"
                        },
                        {
                            "field": "00",
                            "match_all": "00Z"
                        }
                    ]
                },
                "warnings": [
                    {
                        "field": "00",
                        "message": "Invalid search field for this query."
                    }
                ]
            }
        ]
    }
}

管理画面とのマッピングは、下の図のようになります。

FileMakerや自社のAppに取り込んで管理するときは、displayNameよりも、firstName,lastNameに分かれている情報の方が扱いやすいので、画面に表示されている情報以外にも取り込んでおくと後々やりやすいと思います。

また、マッピングをみるとわかるように、「デフォルトの住所」は、defaultAddressというコネクションで管理されています。
配送先の住所とは違うので、注意が必要です。

FileMakerに取り込んでみる

では、我らがFileMakerでスクリプトを組んでテーブルに顧客データを保存してみます。
Claris ConnectでもShopifyのコネクタは用意されていますが、今回使用せず、「url から挿入」で取得してみます。

FileMakerでGraphQLを使うときの注意点は、以下も参考にしてみてください。

テーブルの用意

取り込む分のフィールドを作成しました。

レイアウトの用意

スクリプトで使用するcustomerレイアウトを用意します。
FileMakerでは、新規でテーブルを作成すると、そのテーブルのレイアウトがひとつ出来上がるので、まずはそれを使います。

スクリプトの用意

スクリプトの流れとしては、以下のような感じに組んでいきます。
1.curlでリクエストを投げる
2.取得したJSONデータをテーブルにレコードを追加

2は、取得した分だけテーブルにレコードを登録します。

curlを投げる際のポイントとして、ページネーション(pageInfo)とカーサー(cursor)があります。
1回で取得する件数を指定した場合、顧客情報が指定件数以上あった場合は、次の顧客情報をリクエストする必要があります。
ちなみに、ShopifyにGraphQLでアクセスした時に取得できる最大件数は250件です。

pageInfo

クエリでは、次のページがあるかどうかを取得するpageInfoを指定します。
次のページがない場合は、hasNextPageにFalseが返ってきます。
前のページを指定する場合は、hasPreviousPageでTrueがあったら前のページを取得できます。

    pageInfo{
        hasNextPage
        hasPreviousPage
    }

cursor

cursorは、顧客情報のひとつひとつにあるので、こちらもクエリに指定します。cursorは、今見ている顧客情報がどの位置にいるか、というポインタになります。
cursorは、位置情報なので、edgesの中に指定します。

    edges {
      cursor
      node {
        (顧客情報)...
      }
    }

スクリプト

pageInfoとcursorをクエリに組み合わせると、以下のようになります。
クエリの組み立ては、ページネーションのことを考え、Loopの中で行います。

あとは、いつも通り"url から挿入"のオプションにヘッダとクエリを指定します。

"url から挿入"で返ってきたエラー情報は、必ずチェックです。

問題なければ、FileMakerのテーブルにセットしましょう。
ページネーション用に、hasNextPageとcursorを取得するのをお忘れなく。

これで、テストをしてみましょう。

テスト

ちゃんと取得できた模様です！

コツを掴めば心地いい

Shopifyに限らず、GraphQLのページネーションを覚えてしまえば、どこのGraphQLでも同じ理解で組めると思います。
Shopifyに関していうと、管理画面のどの項目がGraphQLでどう指定すれば取得できるか、をドキュメントや、Postmanで実際に取得してみて合っているかどうかを確認しながら進めるといいですよ！