CRMカード

データ フェッチ リクエスト

「概要」タブにある説明のように、アプリに関連付けられているCRMレコードをユーザーが表示するたびに、HubSpotからそのアプリにデータフェッチ（取得）リクエストが送信されます。これらのリクエストは、ペイロードとして該当するCRMレコードの詳細を付けて、カードに指定されているfetch/targetUrlに送信されます。

レスポンスには最大5つのカードプロパティーを含めることができます。特定のCRMオブジェクトにこれよりも多くのプロパティーがある場合は、アプリからそれらのプロパティーにリンクできます。

リクエストは5秒でタイムアウトすることに注意してください。そのため、3秒で接続を確立する必要があります。 

データ フェッチ リクエストの例：

GET：https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

ヘッダーの内容：

X-HubSpot-Signature： <some base64 string>

X-HubSpot-Signatureヘッダーを使用して、リクエストがHubSpotから送信されていることを確認できます。詳細については、リクエストの署名を参照してください。

クエリーパラメーター：

• userId：データをリクエストしている顧客の数値形式のユーザーID。
• userEmail：データをリクエストしているHubSpotユーザーのEメールアドレス。
• portalId：データをリクエストしている顧客のHubSpotアカウントID。アカウントとポータルは同じ意味で使用されます。 
• associatedObjectId：現在のオブジェクトのID。associatedObjectTypeによってIDのタイプは異なります。チケットの場合は、companyId、dealId、contact vID、objectIdのいずれかです。
• associatedObjectType：ユーザーがリクエストしているデータのオブジェクトタイプ（contact、company、deal、またはticket）。これは、このレコードタイプに指定されているassociatedHubSpotObjectTypesのいずれかです。
• また、リクエストされたいずれかのassociatedHubSpotObjectTypePropertiesの値です。リクエストされたプロパティーのいずれかが現在のオブジェクトで定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。下のスクリーンショットに示されているように、リクエストのプロパティーはアプリ設定UIで定義できます。 

レスポンスの例：

定義：

• results：最大5個の有効なカードプロパティーのリスト。 
• results[].objectId：このオブジェクトの固有ID。このプロパティーは必須です。
• results[].title：このオブジェクトのタイトル。このプロパティーは必須です。
• results[].link：ユーザーがこのオブジェクトに関する詳細を取得するために使用できるURI。任意のプロパティーですが、どのオブジェクトにもリンクがない場合は、値としてnullを指定してください。
• results[].properties：カード設定に定義されていないカスタムプロパティーのリスト。このリストを使用して、特定のオブジェクトに固有のプロパティーを表示することができます。これらのプロパティーは、カード設定で定義されたプロパティーの後に、提示した順に示されます。任意のプロパティーです。
• results[].actions：このオブジェクトに対してユーザーが実行できるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
• totalCount：リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、使用可能なプロパティーの合計数。任意のプロパティーです。
• allItemsLink：リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、その全てのプロパティーを示すURI。任意のプロパティーです。
• itemLabel：「さらに表示」リンクなどで使用されるラベル（例：「チケットをさらに表示」）。任意のプロパティーです。指定がない場合、既定でカードのタイトルが使用されます。
• settingsAction：ユーザーがアプリの設定を更新するために使用できるiframeアクション。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
• primaryAction：レコードタイプのプライマリーアクション（通常は「作成」アクション）。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
• secondaryActions：カードレベルに表示されるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。

上記のプロパティーに加えて、インテグレーターはカード設定で定義されているプロパティーの値を指定できます。上記の例のJSONプロパティーcreatedでは、

"created":"2016-08-04"

このオブジェクトにあらかじめ定義されているcreatedプロパティーの値が返されます。

アクションフックを処理する 

アクションフックとして定義されているアクションをユーザーがクリックすると、HubSpotから、アクション定義に指定されているURIとHTTPメソッドを使用してリクエストが送信されます。

リクエストの例：

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

ヘッダーの内容：

X-HubSpot-Signature： <some base64 string>

クエリーパラメーター：

• userId：データをリクエストしている顧客の数値形式のユーザーID。
• userEmail：データをリクエストしている顧客のHubSpotユーザーEメールアドレス。
• associatedObjectId：現在のオブジェクトのID。associatedObjectTypeによってIDのタイプは異なります。チケットの場合は、companyId、dealId、contact vid、objectIdのいずれかです。
• associatedObjectType：ユーザーがリクエストしているデータのオブジェクトタイプ（contact、company、deal、または ticket）。
• portalId：データをリクエストしている顧客のアカウントID（Hub IDとも呼ばれます）。
• また、リクエストされたいずれかのassociatedObjectPropertiesの値です。リクエストされたプロパティーのいずれかが現在のオブジェクトに定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。

インテグレーターはリクエストがHubSpotから送信されたことを確認するために、X-HubSpot-Signatureヘッダーを使用できます。詳細については、リクエストの署名を参照してください。

レスポンスの例：

{"message":"Successfully deleted object"}

HubSpotは、アクションフックに対するレスポンスをJSONとして解析してメッセージプロパティーを検索しようと試みます。ユーザーには、成功または失敗のいずれかのメッセージが表示されます。

レスポンスのステータスコードが2XXの場合は成功メッセージが表示され、4XXまたは5XXの場合はエラーメッセージが表示されます。

アクションタイプ

ここでは、指定できるアクションの各タイプについて説明します。

iframeアクション

ユーザーがiframeアクションをクリックすると、そのiframeで指定されているURLにあるモーダルダイアログが開きます。

iframeアクションの例：

定義：

• type：iframeアクションであることを示すIFRAMEを指定します。
• width, height：目的のiframeサイズ。
• uri：iframeで開くURI。
• label：アクションドロップダウンに表示されるラベル。
• associatedObjectProperties：関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。Iframeを開く際に、現在のオブジェクトのプロパティー値がクエリーパラメーターとしてURLに付加されます。

モーダルを閉じるための指示

ユーザーがiframeアクションを完了したら、モーダルダイアログを閉じて、ユーザーを元のCRM画面にリダイレクトする必要があります。ダイアログモデルを閉じるには、アプリでwindow.postMessageメッセージを使用できます。次のメッセージを使用できます。

• {"action":"DONE"} - ユーザーが正常にアクションを完了しました。
• {"action":"CANCEL"} -ユーザーがアクションをキャンセルしました。

例：window.parent.postMessage(JSON.stringify({"action":"DONE"}), "*");

注：iframeアクションによってアクセスされたiframeモーダルは、レスポンシブな幅に設定されます。 

アクションフックのアクション

アクションフックのアクションにより、サーバーサイドのリクエストがアプリに送信されます。このアクションでユーザーに表示されるUIは、成功メッセージまたはエラーメッセージのみです。このタイプのアクションは、ユーザー入力を必要としないシンプルな操作に役立ちます。

アクションフックのアクションの例：

定義：

• type：アクションフックのアクションであることを示すACTION_HOOKを指定します。
• httpMethod：リクエストに使用するHTTPメソッド。GET、POST、PUT、DELETE、PATCHのいずれかです。
• uri：リクエストの送信先URI。
• label：アクションドロップダウンに表示するラベル。
• associatedObjectProperties：関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodがGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。

確認アクション

確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。

定義：

• type：アクションフックのアクションであることを示すACTION_HOOKを指定します。
• httpMethod：リクエストに使用するHTTPメソッド。GET、POST、PUT、DELETE、PATCHのいずれかです。
• uri：リクエストの送信先URI。
• label：アクションドロップダウンに表示するラベル。
• associatedObjectProperties：関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodがGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。

確認アクション

確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。

定義：

• type：確認アクションのフックアクションであることを示すCONFIRMATION_ACTION_HOOKを指定します。
• httpMethod：リクエストに使用するHTTPメソッド。GET、POST、PUT、DELETE、PATCHのいずれかです。
• uri：リクエストの送信先URI。
• label：アクションドロップダウンに表示するラベル。
• associatedObjectProperties：関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethodがGETまたはDELETEの場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。
• confirmationMessage：ユーザーへの確認ダイアログに表示するメッセージ。
• confirmButtonText：OKボタンのテキスト。任意。既定では、ボタンのテキストは［OK］に設定されます。
• cancelButtonText：キャンセルボタンのテキスト。任意。既定では、ボタンのテキストは［キャンセル］に設定されます。

アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。