最終更新日: 2025年9月12日
‘ウェブサイトページでGraphQLクエリーからのデータを使用する’; ‘APAC JAPAN (ja) | Dev. Page | Use data from a GraphQL query in your website pages’; ‘ウェブサイトページでGraphQLクエリーのデータを使用する方法について説明します。’; GraphQL（英語）を使用すると、HubSpotのCRMおよびHubDBデータにアクセスするデータクエリーを作成して、データを基にパーソナライズした体験をウェブサイトの訪問者に提供できます。GraphQLの仕組みとクエリーの作成方法について詳しくは、GraphQLを使ったHubSpotのデータ照会（英語）をご参照ください。 GraphQLの仕組みを十分に理解し、必要となるデータを指定するクエリーを作成している場合は、テーマでそのクエリーを使用することができます。
  • 拡張子が.graphqlのファイルにクエリーを保存します。GraphQLクエリーファイルを整理し、相対パスで参照しやすくするため、テーマのルートにある別のディレクトリーにGraphQLクエリーファイルを保持することをお勧めします。
  • HubSpot CLIツールを使用するか、HubSpotアカウントでデザインマネージャーを使用して、クエリーファイルを含むテーマをアップロードします。
GraphQLファイルをアップロードしたら、それらをモジュールまたはテンプレートにバインドできます。これにより、クエリーのデータをモジュールまたはテンプレートのレンダリングコンテキストで使用できるようになります。

​
データクエリーをテンプレートにバインドする

コード内のデータを参照できるようにGraphQLクエリーをテンプレートにバインドするには、dataQueryPathテンプレートアノテーションを追加し、関連付けられているGraphQLクエリーファイルのパスを指定します。パスにファイルの拡張子「.graphql」を含める必要はありません。 例えば、ページ上でクエリーの結果をレンダリングするテンプレートにクエリーファイルをバインドする場合、テンプレートのコードの先頭には次のコードが含まれます。 
<!--
  templateType: page
  isAvailableForNewContent: true
  label: Contact profile page - GraphQL
  dataQueryPath: ../data-queries/contact_info
-->
その後、HubLのdata_query変数から、テンプレートとモジュールコードのデータクエリーへのレスポンスを参照できます。以下の例では、利用可能なロールを格納するHubL変数を定義します。 
{% set contactData = data_query.data.CRM.contact %}

​
データクエリーをモジュールにバインドする

デザインマネージャーを使用して、GraphQLクエリーをモジュールにバインドできます。
  • HubSpotアカウントにて、［マーケティング］＞［ファイルとテンプレート］＞［デザインツール］の順に進みます。
  • ファインダーの最上部で、［ファイル］ドロップダウンメニューをクリックし、［新規ファイル］を選択します。
  • ダイアログボックスで、［今日は何を作成しますか？］ドロップダウンメニューをクリックし、［GraphQL］を選択します。
  • ［次へ］をクリックします。
  • ファイル名を入力し、GraphQLファイルの位置を確認します。
  • クエリーをコピーしてエディターに貼り付け、［変更を公開］をクリックします。
  • クエリーで使用するモジュールに移動します。［リンク済みファイル］で［GraphQLファイル］ドロップダウンメニューをクリックし、クエリーを選択します。
bind-graphql-query-to-module-in-design-manager その後、data_query変数を使用して、モジュールコードでクエリーのレスポンスを参照できます。以下の例では、コンタクトのコレクションの照会データを格納するHubL変数を定義します。 
{% set contactCollectionData = module.data_query.data.CRM.contact_collection %}
ローカルで開発している場合は、モジュールのmeta.jsonファイルにata_query_pathパラメーターを含めて、GraphQLクエリーをモジュールに直接バインドすることをお勧めします。相対パスでクエリーを参照しやすくするため、テーマのルートにある「modules」ディレクトリー内でモジュールを定義するすることをお勧めします。
  • HubSpot CLIツールを使用して、モジュールのディレクトリーをfetch（取得）します。
  • data_query_pathパラメーターを追加し、meta.jsonファイルの位置を基準としたGraphQLクエリーファイルのパスを指定します。例えば、クエリーファイルがテーマのルートにある「data-queries」ディレクトリーにある場合、meta.jsonファイルには以下のコードが含まれます。
// meta.json
{
  "data_query_path": "../../data-queries/contactsQuery"
}
  • 更新したmeta.jsonファイルをHubSpotアカウントにアップロードします。

​
動的コンテキストをクエリーに渡す

特定のリクエストに対して動的なコンテキストがクエリーに必要な場合（例えば、ページの1つにアクセスしているコンタクトのデータなど）、GraphQLクエリーにHubL変数を渡すことができます。
  • 最初に、クエリーの先頭にある単行コメントで#文字を使用して変数を定義します。GraphQLの変数名には規則として、接頭辞に$文字を付加します。例えば、コンタクトのIDの変数を定義するには、次のようになります。
# $contact_id = "{{ request.contact.contact_vid || ''}}"
  • 変数とその型をクエリー定義のパラメーターとして含めます。変数を「non-nullable」としたい場合は、型の後に!を追加します。上記の$contact_id変数をクエリーに渡して特定のコンタクトのコンタクト情報を表示する場合、クエリー定義は次のコードで始まります。
query contact_info($contact_id: String!)
  • 次に変数を参照し、クエリー内のいずれかのフィルターにその変数を引数として渡すことができます。以下のクエリーは、上記の$contact_id変数を使用して、ページにアクセスしているコンタクトの姓、名、Eメールを返します。
# label: "Contact info page"
# description: "Show a contact's name and email"
# $contact_id: "{{request.contact.contact_vid }}"
query contact_info($contact_id: String!) {
  CRM {
    contact(uniqueIdentifier: "id", uniqueIdentifierValue: $contact_id) {
      _metadata {
        id
      }
      firstname
      lastname
      email
    }
  }
}
  • HubL変数のrequest.query_dictを使用して、URLクエリー文字列パラメーターを引数としてGraphQLクエリーに渡すこともできます。例えば、ページURLに「/contacts?location=Boston&department=marketing」が含まれており、GraphQLクエリーでURLクエリーパラメーターを使用してコンタクトを所在地と部署に基づいて絞り込む場合、以下のGraphQLクエリーを使用できます。
# label: "Contact listing page with filters"
# description: "Filter contacts by location and department"
# $location: "{{ request.query_dict.location  || ''}}"
# $department: "{{ request.query_dict.department || ''}"
query contact_listing_page($location: String!, department: $String) {
  CRM {
    contact_collection(filter: {location__eq: $location, department_eq: $department) {
      items {
        _metadata {
         id
        }
        firstname
        lastname
        email
      }
    }
  }
}

​
クエリーデータを使用して動的ページを作成する

CRMデータの特定のプロパティーに基づいてページを動的に生成するには、GraphQLクエリーでディレクティブを使用します。各動的ページは、クエリーでアノテーションを付けたディレクティブからメタデータを取得します。各ディレクティブに定義する値は、検索結果ですぐに特定できるように、そのページのコンテンツを一意に示す値にしてください。 このメタデータには次のディレクティブが含まれます。
動的ページのディレクティブ説明
web_page_canonical_urlページのcanonical URL。
web_page_featured_imageページのキービジュアル。このビジュアルは、ページが共有されると表示されます。
web_page_meta_descriptionページのメタディスクリプション。
web_page_titleページのタイトル。
CRMデータを照会する場合は、これらのディレクティブに加えて、クエリーで一意の識別子として使用するカスタムプロパティーを選択する必要があります。このプロパティーは"hasUniqueValue": trueを使用して構成する必要があります。既存のプロパティーはこのパラメーターを含めるように更新できないため、まだ新しいプロパティーを作成していない場合には、APIを使用して新しいプロパティーを作成する必要があります。

​
動的ページのクエリーとモジュールを作成する

動的ページで使用できるクエリーを作成するには、次の手順に従います。
  • クエリーの先頭に、クエリーのlabelとdescriptionを単行コメントとして含めます。次に、ページの動的スラッグに識別子を関連付けるために別の単行コメントを追加します。
    • HubL変数request.path_param_dictにより提供されるdynamic_slugフィールドに、識別子の名前を設定します。
    • 例えば、コンタクトのプロファイルページを動的に作成するクエリーを作成し、各コンタクトのプロファイルページのスラッグとしてprofile_full_nameという名前のカスタムプロパティーを使用する場合、クエリー定義の上に以下のコメントを含めます。
#$profile_full_name: {{ request.path_param_dict.dynamic_slug }}
  • データソースに一致するIDフィールドをクエリーに含めます。
    • CRMデータを照会する場合は、hs_object_idフィールドを含めます。
    • HUBDBテーブルのデータを照会する場合は、hs_idフィールドを含めます。
  • 上の表の対応するメタデータディレクティブを使用してクエリーのフィールドにアノテーションを付け、各ディレクティブの前に@文字を付けます。例えば、コンタクト プロフィール ページのタイトル、メタディスクリプション、キービジュアルを設定するには、次の手順に従います。
# label: "Contact profile"
# description: "Contact profile query for showing details for a single contact"
# $profile_full_name: {{ request.path_param_dict.dynamic_slug }}
query contact_profile_page($profile_full_name: String!) {
  CRM {
    contact(
      uniqueIdentifier: "profile_full_name"
      uniqueIdentifierValue: $profile_full_name
    ) {
      hs_object_id
      email
      profile_full_name @web_page_title
      profile_description @web_page_meta_description
      profile_picture_url @web_page_featured_image
    }
  }
}
  • 拡張子が.graphqlのファイルにクエリーを保存します。モジュールを設計する際には、HubL変数のdata_queryを使用してクエリーのデータにアクセスできます。

​
リストページのクエリーとモジュールを作成する

用途によっては、動的ページのルートURLでオブジェクトのレコードのリストを表示することがあります。上記の例では、「https://website.com/profiles」に移動したウェブサイト訪問者に対し、全てのコンタクトプロファイルのリストが表示されます。リストページを設定するには、次の手順に従います。
  • リストページに必要な関連オブジェクトレコードのコレクションを取得するため、別のGraphQLクエリーを作成します。
    • クエリーの先頭に、ラベル、説明、およびクエリーに渡す必要のあるその他の変数を単行コメントとして追加します。
    • 必要なフィルターをコレクションフィールドの引数として含めます。
# label: "Profile listing"
# description: "Contact profile listing query for showing all profiles with a "hubspot.com" email address"
query contact_listing {
  CRM {
    contact_collection(filter: { email__contains: "hubspot.com" }) {
      email
      profile_full_name
    }
  }
}
  • リストページのクエリーを.graphql拡張子を使用して保存し、上記の手順に従ってクエリーをリスト ページ モジュールにバインドします。

​
ウェブサイトページを作成する

クエリーを作成し、関連モジュールにバインドしたら、リストページと詳細ページでモジュールを使用できます。
  • リストページを作成するには、次の手順に従います。
    • 新しいページを作成し、ドラッグ&ドロップエリアまたはフレキシブルカラムを含むページテンプレートを選択します。
    • ページエディターで［設定］タブをクリックします。
    • ページタイトルを入力します。
    • ［ページURL］に、動的ページで取得するコレクションに対応するコンテンツスラッグを入力します。上記の例に従うと、コンテンツスラッグは/profilesになります。
    • リストページのメタディスクリプションを入力し、［コンテンツ］タブをクリックしてエディターに戻ります。
    • 左側のサイドバーの［追加］タブで、リスト ページ モジュールを見つけてページエディター内にドラッグします。
    • ページのデザインが完了したら、右上の［公開］をクリックして公開します。
  • 次に、詳細ページを設定します。
    • 新しいページを作成し、ドラッグ&ドロップエリアまたはフレキシブルカラムを含むページテンプレートを選択します。
    • ページエディターで［設定］タブをクリックします。
    • ページタイトルを入力します。
    • ［ページURL］の鉛筆アイコンをクリックして、ページのURLを編集します。リストページを表示する場所をURLに設定します。上記の例ではリストページは/profilesにあります。このため、ページの完全なコンテンツスラッグは/profiles/[:dynamic-slug]になります。
    • ［詳細オプション］をクリックし、［動的ページ］セクションまでスクロールします。
    • ［動的ページ］の下の［データソース］ドロップダウンメニューをクリックし、GraphQLクエリーの先頭に含まれているラベルに一致するラベルを選択します。
    • ページ上部にある［コンテンツ］タブをクリックして、エディターに戻ります。
    • 左側のサイドバーの［追加］タブで、詳細モジュールを見つけてページエディター内にドラッグします。
    • 準備ができたら、右上にある［公開］をクリックしてページを公開します。

​
関連情報

GraphQLクエリーを作成、テスト、調整する方法について詳しくは、GraphQLを使ったHubSpotのデータ照会（英語）をご参照ください。