Salesforce Marketing Cloud

Salesforce Marketing Cloud コネクタを使用すると、Salesforce Marketing Cloud データセットに対して、挿入、削除、更新、読み取りオペレーションを実行できます。

準備

Salesforce Marketing Cloud コネクタを使用する前に、以下の作業を行ってください。

Google Cloud プロジェクトで次の操作を行います。
- コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
- コネクタに使用するサービスアカウントに、次の IAM ロールを付与します。
  - roles/secretmanager.viewer
  - roles/secretmanager.secretAccessor
  サービスアカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービスアカウントがない場合は、サービスアカウントを作成する必要があります。詳細については、サービスアカウントを作成するをご覧ください。
- 次のサービスを有効にします。
  - secretmanager.googleapis.com（Secret Manager API）
  - connectors.googleapis.com（Connectors API）
  サービスを有効にする方法については、サービスを有効にするをご覧ください。
以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース（バックエンドシステム）への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。
[接続] ページに移動
[+ 新規作成] をクリックして [接続の作成] ページを開きます。
[ロケーション] セクションで、接続のロケーションを選択します。
1. リージョン: プルダウンリストからロケーションを選択します
  サポートされているすべてのリージョンのリストについては、ロケーションをご覧ください。
2. [NEXT] をクリックします。
[接続の詳細] セクションで、次の操作を行います。
1. Connector: 使用可能なコネクタのプルダウンリストから [Salesforce Marketing Cloud] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 63 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
6. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
7. API Integration Type: OAuth フローの許可タイプ。有効なエントリは、Server-to-Server と Web-App です。
8. Account Id: 目的のビジネスユニットのアカウント ID（MID）
9. Display Child Data Extensions: 子アカウントのデータ拡張機能が設定されている場合は、表示します。
10. Instance: 使用される Salesforce Marketing Cloud API のインスタンス。
11. List Data Extensions: データ拡張機能をテーブルとしてリスト化するかどうかを決定するブール値。
12. Query All Accounts: イベントに関連するすべてのアカウント（親とすべての子を含む）を照会します。
13. Schema: 接続先の Salesforce Marketing Cloud サーバーのバージョンを指定します。
14. Subdomain: Salesforce Marketing Cloud API のサブドメイン。
15. Use Legacy Authentication: 以前の認証を使用して Salesforce Marketing Cloud REST API に接続するかどうかを決定するブール値。
16. Use proxy: このチェックボックスを選択して、接続用のプロキシサーバーを構成し、次の値を構成します。
17. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
18. [NEXT] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  Salesforce Marketing Cloud 接続では、次の認証タイプがサポートされています。
  - ユーザー名とパスワードを指定する
2. [NEXT] をクリックします。
Review: 接続と認証の詳細を確認します。
[Create（作成）] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

ユーザー名とパスワード
- ユーザー名: コネクタのユーザー名
- パスワード: コネクタに関連付けられたパスワードを含む Secret Manager の Secret。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベースコネクタでは、テーブルがエンティティであり、ファイルサーバーコネクタでは、フォルダがエンティティです。また、メッセージングシステムコネクタでは、キューがエンティティです。
ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。
オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。
- リスト
- 取得
- 作成
- 更新
- 削除
使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティオペレーションをご覧ください。ただし、コネクタがどのエンティティオペレーションもサポートしていない場合、サポートされていないオペレーションは Operations リストに表示されません。
アクション: コネクタインターフェースを介して統合で使用できる最初のクラス関数です。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

システムの上限

Salesforce Marketing Cloud コネクタは、ノードごとに 1 秒あたり最大 7 件のトランザクションを処理でき、この上限を超えるトランザクションをスロットルします。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます（可用性を高めるため）。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

注: Integration Connectors ノードの数は、使用状況に応じて動的に自動スケーリングされます。ただし、自動スケーリングを待たずに大量の容量を確保する場合は、接続の最小ノード値を調整できます。1 つの接続により多くのトランザクションを処理するには、より多くのノードが必要です。逆に、接続が処理するトランザクションが少ない場合は、必要なノードの数が少なくなります。ノードの値を構成するには、次の手順を行います。

従量課金制をご利用のお客様は、接続の編集ページでノードの最小値と最大値を構成します。
サブスクリプションベースで利用されているお客様は、サポートにお問い合わせください。

ノードが処理できる最大トランザクションは、さまざまな要因によって異なります。そのため、スループットを高めるために最小ノードを調整する前に、バックエンドシステムが必要なトラフィックを処理するために最適に設定されているかどうかを確認することをおすすめします。

アクション

このセクションでは、Salesforce Marketing Cloud 接続でサポートされているすべての操作を一覧表示します。

GetJourneyPublicationStatus アクション

このアクションは、パブリケーションの公開ステータスを取得します。

GetJourneyPublicationStatus アクションの入力パラメータ

パラメータ名	データ型	必須	説明
StatusId	文字列	正しい	ジャーニーのパブリケーションのステータス ID。

GetJourneyPublicationStatus アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

GetJourneyPublicationStatus アクションの構成例については、例をご覧ください。

FireEntryEvent アクション

プログラムを開始するエントリイベントを起動します。

FireEntryEvent アクションの入力パラメータ

パラメータ名	データ型	必須	説明
ContactKey	文字列	正しい	サブスクライバーまたは連絡先を一意に識別する ID
EventDefinitionKey	文字列	正しい	イベントを作成して保存した後、イベント管理で EventDefinitionKey を見つけます。これは、標準イベントとカスタムイベントの両方に当てはまります。イベント定義キーにピリオドを含めないでください。
データ	文字列	False	イベントのプロパティ。カスタムイベントで定義されているか、イベントによって定義される場合にのみ必要です。

FireEntryEvent アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

FireEntryEvent アクションの構成例については、例をご覧ください。

StopJourney アクション

実行中のステップを停止

StopJourney アクションの入力パラメータ

パラメータ名	データ型	必須	説明
JourneyId	文字列	正しい	停止の工程の ID。GUID（UUID）の形式で表されます。
JourneyVersion	整数	正しい	停止する工程のバージョン番号

StopJourney アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

StopJourney アクションの構成例については、例をご覧ください。

PublishJourney アクション

PublishJourney Action - 工程バージョンを非同期で公開

PublishJourney アクションの入力パラメータ

パラメータ名	データ型	必須	説明
JourneyId	文字列	正しい	停止の工程の ID。GUID（UUID）の形式で表されます。
JourneyVersion	整数	正しい	停止する工程のバージョン番号。

PublishJourney アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

PublishJourney アクションの構成例については、例をご覧ください。

CreateTriggeredSend アクション

CreateTriggeredSend アクション: トリガーされるメール送信の特定のインスタンスを表す、トリガーされた送信オブジェクトを作成します

CreateTriggeredSend アクションの入力パラメータ

パラメータ名	データ型	必須	説明
キー	文字列	False	トリガーされる送信に関連する定義を定義します。このプロパティは、マーケティングクラウドのオブジェクトに割り当てられた外部キーに対応します。
SendId	文字列	False	TriggeredSendDefinition の作成時にレスポンスから送信されるエントリイベント送信定義の ID。鍵か外部鍵が必要です。
FromAddress	文字列	False	送信元として表示されるメールアドレス。
FromName	文字列	False	送信者の名前
ToAddress	文字列	正しい	メッセージ受信者のメールアドレス。
SubscriberKey	文字列	正しい	メッセージ受信者に対して定義された一意の識別子。
SubscriberAttributes	文字列	False	メッセージに定義されているサブスクライバー属性の名前と値のペア。
RequestType	文字列	False	有効な値は ASYNC と SYNC です。定義されていない場合、デフォルト値は ASYNC です。リクエストを非同期で処理するかどうかを指定します。

CreateTriggeredSend アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

CreateTriggeredSend アクションの構成例については、例をご覧ください。

SendTransactionalMessageToRecipient アクション

SendTransactionalMessageToRecipient アクション送信定義を使用して、単一の受信者にメッセージを送信

SendTransactionalMessageToRecipient アクションの入力パラメータ

パラメータ名	データ型	必須	説明
MessageKey	文字列	正しい	ユーザー定義のメッセージ ID。
DefinitionKey	文字列	正しい	定義の一意の識別子。
RecipientContactKey	文字列	正しい	Marketing Cloud のサブスクライバーの一意の識別子。各リクエストには contactKey を含める必要があります。受信者のメールアドレスを使用して、既存のサブスクライバーキーを使用するか、送信時にキーを作成できます。
RecipientTo	文字列	False	受信者のチャネルアドレス。メールの場合、受信者のメールアドレスです
属性	文字列	False	受信者のメールのカスタマイズに使用される情報。鍵ペアとして記述されます。属性が、プロファイル属性、コンテンツ属性、またはトリガーされた送信データ拡張子の属性と一致している

SendTransactionalMessageToRecipient アクションの出力パラメータ

このアクションは、すべての結果を示すレスポンスの本文でステータス 200（OK）を返します。

SendTransactionalMessageToRecipient アクションの構成例については、例をご覧ください。

例

このセクションでは、このコネクタでエンティティオペレーションとアクションの一部を実行する方法について説明します。

例 - ジャーニーのパブリケーションのステータスを取得する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[GetJourneyPublicationStatus] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "StatusId": "3acf1f54-5c9e-4719-b7f7-bfc2e5caf10a"
}
```

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

 [{
  "Status": "PublishCompleted",
  "Message": null
}]

例 - エントリイベントを起動して工程を開始する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[FireEntryEvent] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "ContactKey": "Email",
  "EventDefinitionKey": "APIEvent-4d84e619-a629-6b17-945f-9a6e78a1982c",
  "Data": "{\"Email\": \"usr1@test.com\"}"
}
```

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

 [{
  "EventInstanceId": "0d6f6dd1-1aaa-4eec-9727-f99550ab68f9"
}]

例 - 実行中のステップを停止する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[StopJourney] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "JourneyId": "37D2789E-2B1D-433E-8E18-8F47E4D8E865",
  "JourneyVersion": 1.0
}
```

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

  [{
  "Success": true
}]

例 - ジャーニーバージョンを公開する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[PublishJourney] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "JourneyId": "0868BF36-3107-460E-9EF1-09633A0592E8",
  "JourneyVersion": 1.0
}
```

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

 [{
  "StatusId": "acb1734d-483e-400a-97d7-0501b94f03b2"
}]

例 - トリガーを作成してトリガーを開始する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[CreateTriggeredSend] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "Key": "BU27_SendDefinition1",
  "ToAddress": "usr1@test.com",
  "SubscriberKey": "107",
  "SubscriberAttributes": "{\"FirstName\": \"John\", \"LastName\": \"P\"}"
}
```

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

 [{
  "Success": "True",
  "RecipientSendId": "5d06edb1-d07c-48ad-a1f2-d6350eb863f8",
  "Messages": "Queued"
}]

例 - 1 人の受信者にメッセージを送信する

[Configure connector task] ダイアログで、[Actions] をクリックします。
[SendTransactionalMessageToRecipient] アクションを選択してから、[完了] をクリックします。

[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。

{
  "MessageKey": "T9999009",
  "DefinitionKey": "Send-Definition-SFMC-Demo-2",
  "RecipientContactKey": "107",
  "RecipientTo": "usr1@test.com",
  "Attributes": "FirstName :John"
}

アクションが成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。

[{
  "RequestId": "d8fb9e9e-3ae2-412f-b01e-d198433cfc16"
}]

例 - エンティティ内のレコードの一覧表示

この例では、Assets エンティティ内のレコードを一覧表示します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Assets を選択します。
[LIST] オペレーションを選択し、[完了] をクリックします。
コネクタタスクの [タスク入力] セクションで、要件に応じて filterClause を設定できます。

たとえば、フィルタ句を Location='US' and region='us-east1' に設定すると、リージョンが us-east1 の米国内のレコードのみが表示されます。

例 - エンティティからレコードを取得する

この例では、Assets エンティティから 1 つのレコードを取得します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Assets を選択します。
[GET] オペレーションを選択し、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで [EntityId] をクリックし、[デフォルト値] フィールドに 49851 を入力します。
ここで、49851 は Assets エンティティの主キーです。

例 - エンティティからレコードを削除する

この例では、Assets エンティティからレコードを削除します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Assets を選択します。
[DELETE] オペレーションを選択してから、[完了] をクリックします。
[コネクタタスクの [タスク入力 セクションで [entityId] をクリックし、[デフォルト値] フィールドに 49851 を入力します。

例 - エンティティ内にレコードを作成する

この例では、DataExtensionObject_Custom エンティティにレコードを作成します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
[Entity] リストから [DataExtensionObject_Custom] を選択します。
[Create] オペレーションを選択し、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
    "StudentName":"John",
    "StudentID":"1",
    "Rank":"1"}
```
統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。
```
 {
      "StudentID": 1
    } 
```

例 - エンティティ内のレコードの更新

この例では、Journeys エンティティにレコードを作成します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Journeys を選択します。
[Update] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
  "Name": "SFMC_CRETAE_JOURNEY_V1"
}
```
エンティティ ID を Journeys のエンティティに設定します。エンティティ ID を設定するには、[エンティティ ID] をクリックし、[デフォルト値] フィールドに「0868BF36-3107-460E-9EF1-09633A0592E8」と入力します。
統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。
```
{
  "Id": "0868bf36-3107-460e-9ef1-09633a0592e8"
}
```

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプルテンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名	データ型	必須	説明
apiintegration_type	ENUM	False	OAuth フローの許可タイプ。有効なエントリは、Server-to-Server と Web-App です。サポートされている値は、Server-to-Server、Web-App です。
schema	ENUM	正しい	接続先の Salesforce Marketing Cloud API を指定します。サポートされている値は REST、SOAP です。
account_id	文字列	False	目的のビジネスユニットのアカウント ID（MID）
display_child_data_extensions	BOOLEAN	False	子アカウントのデータ拡張機能が設定されている場合は、表示します。
インスタンス	文字列	False	使用される Salesforce Marketing Cloud API のインスタンス。注: インスタンスが s10 より大きい場合、サブドメインを指定する必要があります。
list_data_extensions	BOOLEAN	False	データ拡張機能をテーブルとしてリスト化するかどうかを決定するブール値。
query_all_accounts	BOOLEAN	False	イベントに関連するすべてのアカウント（親とすべての子を含む）を照会します。
詳細度	文字列	False	接続の詳細レベルは 1～5 です。詳細レベルが高いと、すべての通信の詳細（リクエスト、レスポンス、SSL 証明書）がログに記録されます。
サブドメイン	文字列	False	Salesforce Marketing Cloud API のサブドメイン。
proxy_enabled	BOOLEAN	False	接続用のプロキシサーバーを構成するには、このチェックボックスをオンにします。
proxy_auth_scheme	ENUM	False	ProxyServer プロキシへの認証に使用する認証タイプです。サポートされている値は、BASIC、DIGEST、NONE です。
proxy_user	文字列	False	ProxyServer プロキシへの認証に使用されるユーザー名です。
proxy_password	SECRET	False	ProxyServer プロキシの認証に使用されるパスワード。
proxy_ssltype	ENUM	False	ProxyServer プロキシへの接続時に使用する SSL のタイプです。サポートされている値は AUTO、ALWAYS、NEVER、TUNNEL です。

インテグレーションで Salesforce Marketing Cloud 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

Salesforce Marketing Cloud

準備

コネクタを構成する

認証を構成する

エンティティ、オペレーション、アクション

システムの上限

アクション

GetJourneyPublicationStatus アクション

GetJourneyPublicationStatus アクションの入力パラメータ

GetJourneyPublicationStatus アクションの出力パラメータ

FireEntryEvent アクション

FireEntryEvent アクションの入力パラメータ

FireEntryEvent アクションの出力パラメータ

StopJourney アクション

StopJourney アクションの入力パラメータ

StopJourney アクションの出力パラメータ

PublishJourney アクション

PublishJourney アクションの入力パラメータ

PublishJourney アクションの出力パラメータ

CreateTriggeredSend アクション

CreateTriggeredSend アクションの入力パラメータ

CreateTriggeredSend アクションの出力パラメータ

SendTransactionalMessageToRecipient アクション

SendTransactionalMessageToRecipient アクションの入力パラメータ

SendTransactionalMessageToRecipient アクションの出力パラメータ

例

例 - ジャーニーのパブリケーションのステータスを取得する

例 - エントリ イベントを起動して工程を開始する

例 - 実行中のステップを停止する

例 - ジャーニー バージョンを公開する

例 - トリガーを作成してトリガーを開始する

例 - 1 人の受信者にメッセージを送信する

例 - エンティティ内のレコードの一覧表示

例 - エンティティからレコードを取得する

例 - エンティティからレコードを削除する

例 - エンティティ内にレコードを作成する

例 - エンティティ内のレコードの更新

Terraform を使用して接続を作成する

インテグレーションで Salesforce Marketing Cloud 接続を使用する

Google Cloud コミュニティの助けを借りる

次のステップ

例 - エントリイベントを起動して工程を開始する

例 - ジャーニーバージョンを公開する