Shopify Import Custom Query Integration V2

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

Shopify Import Connector V2—カスタムクエリは、ShopifyのGraphQL Admin APIと連携し、ユーザーが独自の必要なクエリを定義できるように設計されています。Shopify Import Integration V2で以前実装された機能を引き続き開発します。

新しいインポート操作を追加します：

• カスタムクエリインポート
  • 4種類のクエリをサポート：
• クエリ - 複数形のオブジェクトからの通常クエリ
• クエリ - 単数形のオブジェクトからの通常クエリ（idなどの必須フィールドによるフィルタが必要）
• 複数形のNODESを使用したクエリ
• 単数形のNODEを使用したクエリ

前提条件

• Treasure Dataの基本知識
• Shopifyの基本知識

要件と制限事項

• Metafieldインポートの制限
  • 製品ごとに最大250個のmetafield
  • 製品バリアントごとに最大250個のmetafield
• Product Variantsのインポートは、created_atタイムスタンプによる増分読み込みをサポートしなくなりました。現在はupdated_atタイムスタンプによる読み込みのみをサポートしています。

Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります: https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/

TDコンソール経由でShopifyレポートをインポートする

認証を作成する

最初のステップは、認証情報のセットで新しい認証を作成することです。

1. Integrations Hubを選択します。
2. Catalogを選択します。

3. CatalogでShopifyを検索し、アイコンの上にマウスを置いてCreate Authenticationを選択します。

4. Credentialsタブが選択されていることを確認し、統合の認証情報を入力します。

新しい認証フィールド

1. Continueを選択します。
2. 認証の名前を入力し、Doneを選択します。

カスタムクエリソースを作成する

認証がコンソールで使用可能になったら、インポートジョブを設定します。

1. TDコンソールを開きます。
2. Integrations Hub > Authenticationsに移動します。
3. Shopify認証を見つけて、New Sourceを選択します。

接続を作成する

1. Data Transfer Nameフィールドにソース名を入力します。
2. Nextを選択します。

ソーステーブルを識別する

1. ソーステーブルのフィールドを設定します

1. Nextを選択します。

データ設定を定義する

1. データ設定を構成します。

• 注意：
  • JSONフィールドのトップレベル1のみをサポートします。JSONオブジェクトのキーと値のペアの解析はサポートしていません。
  • データを取得するには、JSONフィールドをstringからJSONデータタイプに変更することを忘れないでください。通常、推測されたフィールドデータタイプはstringです。
  • 必要がない場合は、フィールド名を変更しないでください。
  • カスタムクエリで何かを変更した後は、スキーマ設定を再度確認して編集する必要があります。

Data Preview

インポートを実行する前に、Generate Preview を選択してデータのプレビューを表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。

1. Next を選択します。Data Preview ページが開きます。
2. データをプレビューする場合は、Generate Preview を選択します。
3. データを確認します。

Data Placement

データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。

1. Next を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。

2. Database を選択 > Select an existing または Create New Database を選択します。

3. オプションで、database 名を入力します。

4. Table を選択 > Select an existing または Create New Table を選択します。

5. オプションで、table 名を入力します。

6. データをインポートする方法を選択します。

   • Append (デフォルト) - データインポートの結果は table に追加されます。 table が存在しない場合は作成されます。
   • Always Replace - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。
   • Replace on New Data - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。

7. Timestamp-based Partition Key 列を選択します。 デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。

8. データストレージの Timezone を選択します。

9. Schedule の下で、このクエリを実行するタイミングと頻度を選択できます。

一度だけ実行

1. Off を選択します。
2. Scheduling Timezone を選択します。
3. Create & Run Now を選択します。

定期的に繰り返す

1. On を選択します。
2. Schedule を選択します。UI では、@hourly、@daily、@monthly、またはカスタム cron の 4 つのオプションが提供されます。
3. Delay Transfer を選択して、実行時間の遅延を追加することもできます。
4. Scheduling Timezone を選択します。
5. Create & Run Now を選択します。

転送が実行された後、Data Workbench > Databases で転送の結果を確認できます。

ワークフロー経由でShopifyレポートをインポートする

td_load>: src_idを使用してワークフロー経由でShopifyレポートからデータをインポートできます。既にソースを作成している場合は実行できます。ソースを作成したくない場合は、.ymlファイルを使用してインポートできます。

ソースを使用する

1. Integrations Hub>Sourcesを選択します。
2. 画面の右端のFiltersペインで、Integration Typeドロップダウンメニューを使用してShopify V2を選択します。
3. Sourcesペインで、使用するソースを含む行を識別し、その行のmore（•••アイコン）ドロップダウンメニューを使用してCopy Unique IDを選択します。

1. ワークフロータスクを定義し、td_load>:にステップ3でコピーしたIDを使用します。

+load:
   td_load>: unique_id_of_your_source
   database: ${td.dest_db}
   table: ${td.dest_table}

2. ワークフローを実行します。

.ymlファイルを使用する

1. .ymlファイルを識別します。

.ymlファイルを作成する必要がある場合は、Create Seed Config File (seed.yml)に記載されている手順を参照してください。 2. ワークフロータスクを定義し、td_load>: に.ymlファイルを指定します。

+load:
  td_load>: config/daily_load.yml
  database: ${td.dest_db}
  table: ${td.dest_table}

3. ワークフローを実行します。

サンプルワークフローコード

サンプルワークフローコードについては、Treasure Boxesをご覧ください。

CLI (Toolbelt) を使用したShopifyからのインポート

統合を設定する前に、最新バージョンのTD Toolbeltをインストールしてください。

ロードファイルの準備

in:
  type: shopify_v2
  admin_api_access_token: xxxxxxxx
  target: custom_query
  store_name: xxxxxxx
  from_date: '2024-12-31T17:00:00.000Z'
  incremental_field: created_at
  incremental: true
  query: |
    {
      products(first: 10, query: "{{incremental_filter}}") {
        pageInfo {
            hasNextPage
            endCursor
          }
          edges {
            node {
              id
              title
              productType
              createdAt
              ...
              ...
              ...
            }
          }
        }
    }
out:
  mode: replace

パラメータリファレンス

データを推測するには、 td connector:guess コマンドを使用します。(最初にguessを使用してスキーマを推測し、"columns"プロパティで期待通りにスキーマを変更する必要があります)。

$ td connector:guess guess.yml

in:
  type: shopify_v2
  admin_api_access_token: xxxxxxxx
  target: custom_query
  store_name: xxxxxxx
  from_date: '2024-12-31T17:00:00.000Z'
  incremental_field: created_at
  incremental: true
  query: |
    {
      products(first: 10, query: "{{incremental_filter}}") {
        pageInfo {
            hasNextPage
            endCursor
          }
          edges {
            node {
              id
              title
              productType
              createdAt
              ...
              ...
              ...
            }
          }
        }
    }
out:
  mode: replace

データをプレビューするには、 td connector:preview コマンドを使用します。

$ td connector:preview load.yml

ロードジョブの実行

データのサイズによっては、数時間かかる場合があります。データを保存するTreasure Dataデータベースとテーブルを必ず指定してください。Treasure Dataのストレージは時間で分割されているため、--time-columnオプションを指定することをお勧めします(データパーティショニングを参照)。このオプションが指定されていない場合、データコネクタは最初のlongまたはtimestamp列をパーティショニング時間として選択します。--time-columnで指定される列の型は、longまたはtimestamp型のいずれかである必要があります。

データに時間列がない場合は、add_timeフィルターオプションを使用して時間列を追加できます。詳細については、add_time Filter Functionのドキュメントを参照してください。

$ td connector:issue load.yml --database td_sample_db --table td_sample_table \--time-column created_at

connector:issueコマンドは、データベース(td_sample_db)とテーブル(td_sample_table)が既に作成されていることを前提としています。データベースまたはテーブルがTDに存在しない場合、このコマンドは失敗します。データベースとテーブルを手動で作成するか、td connector:issueコマンドで--auto-create-tableオプションを使用してデータベースとテーブルを自動作成してください。

$ td connector:issue load.yml --database td_sample_db --table td_sample_table--time-column created_at --auto-create-table

データコネクタはサーバー側でレコードをソートしません。時間ベースのパーティショニングを効果的に使用するには、事前にファイル内のレコードをソートしてください。

timeというフィールドがある場合は、--time-columnオプションを指定する必要はありません。

$ td connector:issue load.yml --database td_sample_db --table td_sample_table

インポートモード

load.ymlファイルのout:セクションでファイルインポートモードを指定します。out:セクションは、データがTreasure Dataテーブルにインポートされる方法を制御します。たとえば、既存のテーブルにデータを追加したり、データを置き換えたりすることができます。

実行のスケジューリング

増分ファイルインポートのために、定期的なデータコネクタの実行をスケジュールできます。Treasure Dataスケジューラは高可用性を確保するために最適化されています。

スケジュールされたインポートでは、指定されたプレフィックスに一致し、次のいずれかの条件を満たすすべてのファイルをインポートできます:

• use_modified_timeが無効になっている場合、最後のパスは次の実行のために保存されます。2回目以降の実行では、統合はアルファベット順で最後のパスの後に来るファイルのみをインポートします。
• それ以外の場合、ジョブが実行された時刻が次の実行のために保存されます。2回目以降の実行では、コネクタはその実行時刻以降にアルファベット順で変更されたファイルのみをインポートします。

TD Toolbeltを使用したスケジュールの作成

新しいスケジュールは、td connector:createコマンドを使用して作成できます。

$ td connector:create daily_import "10 0 * * *" \td_sample_db td_sample_table load.yml

Treasure Dataのストレージは時間で分割されているため、--time-columnオプションを指定することもお勧めします(データパーティショニングを参照)。

$ td connector:create daily_import "10 0 * * *" \td_sample_db td_sample_table load.yml \--time-column created_at

cronパラメータは、@hourly、@daily、@monthlyの3つの特別なオプションも受け入れます。

デフォルトでは、スケジュールはUTCタイムゾーンで設定されます。-tまたは--timezoneオプションを使用して、タイムゾーンでスケジュールを設定できます。--timezoneオプションは、Asia/Tokyo、America/Los_Angelesなどの拡張タイムゾーン形式のみをサポートします。PST、CSTなどのタイムゾーン略語はサポートされておらず、予期しないスケジュールになる可能性があります。