Salesforce Marketing Cloud コネクタ

Select

Salesforce Marketing Cloud コネクタを使用すると、Marketing Cloud API Web サービス (現在は Marketing Cloud API といい、Salesforce Marketing Cloud ともいいます) に接続できます。このコネクタは、Salesforce Marketing Cloud の機能を利用した便利な操作を公開します。

前提条件

このドキュメントは、読者が Salesforce Marketing、Mule、Anypoint コネクタ、Anypoint Studio、Mule の概念、Mule フローの要素、グローバル要素に精通していることを前提としています。

対象リソースへの接続をテストするには、ログイン情報が必要です。

ハードウェアとソフトウェアの要件および互換性に関する情報は、「コネクタリリースノート」を参照してください。

Maven でこのコネクタを使用するには、Anypoint Exchange の [Dependency Snippets (連動関係スニペット)] で pom.xml の連動関係情報を確認してください。

このコネクタの新機能

現在ではどの操作でも、POJO ではなく、マップが返されます。マップは、旧来の POJO の項目名をキー、項目値を値として表します。

Design Center での接続方法

  1. トリガをクリックします。トリガ時にこのコネクタを選択することで、グローバル要素を作成できます。 グローバル要素が不要な場合は、HTTP リスナまたはスケジューラトリガを使用できます。

  2. このコネクタのグローバル要素 (省略可能) を作成するには、次の項目を設定します。

    Design Center のグローバル要素
  3. 詳細は、このドキュメントの「ユーザ名パスワードの必須パラメータ」と「関連情報」セクションの「ユーザ名パスワード」を参照してください。

  4. 「OAuth ユーザ名パスワードの必須パラメータ」と「関連情報」の「OAuth ユーザ名パスワード」を参照してください。

  5. プラス記号を選択して、コンポーネントを追加します。

  6. コンポーネントとしてコネクタを選択します。

  7. 次の項目を設定します。

    • Create:

      • Object Type (オブジェクト種別) - 作成する API オブジェクトの種別

      • Api Objects (API オブジェクト) - 1 つ以上の API オブジェクトの配列

        Create の項目
    • Delete:

      • Object Type (オブジェクト種別) - 削除する API オブジェクトの種別

      • Api Objects (API オブジェクト) - 1 つ以上の API オブジェクトの配列

        Delete の項目
    • Query:

      • Object Type (オブジェクト種別) - 更新する API オブジェクトの種別

      • Api Objects (API オブジェクト) - 1 つ以上の API オブジェクトの配列

        SMC-update
    • Upsert:

      • Object Type (オブジェクト種別) - 更新/挿入する API オブジェクトの種別

      • Api Objects (API オブジェクト) - 1 つ以上の API オブジェクトの配列

        SMC-upsert
    • Configure Create:

      • Object Type (オブジェクト種別) - 設定の種別

      • Configurations (設定) - 作成する 1 つ以上の設定の配列

        DC-configure-create
    • Configure Update:

      • Object Type (オブジェクト種別) - 設定の種別

      • Configurations (設定) - 更新する 1 つ以上の設定の配列

        DC-configure-update
    • Configure Delete:

      • Object Type (オブジェクト種別) - 設定の種別

      • Configurations (設定) - 削除する 1 つ以上の設定の配列

        DC-configure-delete
    • Perform Start:

      • Object Type (オブジェクト種別) - perform を実行するオブジェクトの種別

      • Definitions (定義) - perform 操作の 1 つ以上の定義の配列

        DC-perform-start
    • Perform Stop:

      • Object Type (オブジェクト種別) - perform 操作の停止アクションをサポートするオブジェクトの種別

      • Definitions (定義) - perform 操作の 1 つ以上の定義の配列

        DC-perform-stop
    • Perform Get Max Count:

      • Object Type (オブジェクト種別) - perform を実行するオブジェクトの種別

      • Definitions (定義) - perform 操作の 1 つ以上の定義の配列

        DC-perform-get-max-count
    • Schedule Start:

      • Object Type (オブジェクト種別) - schedule を実行するオブジェクトの種別

      • Interactions (インタラクション) - schedule 操作の 1 つ以上のインタラクションの配列

        DC-schedule-start
    • Retrieve:

      • Query (クエリ) - 取得するオブジェクトを説明するクエリ

        DC-retrieve

ユーザ名パスワードの必須パラメータ

  • Username (ユーザ名) - セッションの初期化に使用するユーザ名

  • Password (パスワード) - ユーザの認証に使用するパスワード

    user-pass-config

OAuth ユーザ名パスワードの必須パラメータ

  • Client ID (クライアント ID) - インストール済みパッケージのクライアント ID

  • Client Secret (クライアントシークレット) - インストール済みパッケージのクライアントシークレット

  • OAuth Endpoint (OAuth エンドポイント) - API キーの発行を担う ID プロバイダ (IDP) のエンドポイント

  • Soap Endpoint (SOAP エンドポイント) - API キーの発行に使用するサービスをホストするサービスプロバイダ (SP) のエンドポイント

    user-pass-config

    注意: クライアントの ID とシークレットを保存する場合は十分に注意します。JavaScript を使用してクライアント側でこの情報を公開したり、モバイルアプリケーションに保存したりしないでください。これらのログイン情報は必ずアプリケーションにセキュアに保存します。

Anypoint Studio 7 での接続

Anyconnect Studio でこのコネクタを使用するには、最初に Exchange からダウンロードし、必要に応じて設定します。

Studio でのコネクタのインストール

  1. Anypoint Studio で、Studio タスクバーの Exchange アイコンをクリックします。

  2. Anypoint Exchange で [Login (ログイン)] をクリックします。

  3. このコネクタを検索して [Install (インストール)] をクリックします。

  4. 画面の指示に従ってこのコネクタをインストールします。

Studio の更新がある場合、右下隅にメッセージが表示されます。メッセージをクリックすると、更新をインストールできます。

Studio での設定

  1. コネクタをドラッグして Studio キャンバスにドロップします。

  2. コネクタのグローバル要素を作成するには、次の項目を設定します。

    1. ユーザ名パスワード:

      • Username (ユーザ名) - セッションの初期化に使用するユーザ名

      • Password (パスワード) - ユーザの認証に使用するパスワード

        user-pass-config
    2. OAuth ユーザ名パスワード:

      • Client ID (クライアント ID) - インストール済みパッケージのクライアント ID

      • Client Secret (クライアントシークレット) - インストール済みパッケージのクライアントシークレット

      • OAuth Endpoint (OAuth エンドポイント) - API キーの発行を担う ID プロバイダ (IDP) のエンドポイント

      • Soap Endpoint (SOAP エンドポイント) - API キーの発行に使用するサービスをホストするサービスプロバイダ (SP) のエンドポイント

        user-pass-config

ユースケース - オブジェクトを作成する

  1. 新しい Mule プロジェクトを作成するには、[File (ファイル)] > [New (新規)] > [Mule Project (Mule プロジェクト)] をクリックします。

  2. プロジェクトの名前を入力して、[Finish (完了)] をクリックします。

    新しいプロジェクトのダイアログ
  3. pom.xml を開き、dependencies セクションに、Mule Salesforce Marketing コネクタの以下の連動関係を追加しますが、その前に --VERSION-- を使用可能な最新バージョンに置換します。

    <dependency>
        <groupId>org.mule.connectors</groupId>
        <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
        <version>--VERSION--</version>
        <classifier>mule-plugin</classifier>
    </dependency>
  4. フローを作成します。

プロジェクトの構造をナビゲートして、src/main/app/smc-usecase-create-object.xml をダブルクリックし、次の手順に従います。

  1. パレットで [HTTP] > [Listener (リスナ)] 要素を探します。

  2. [Listener (リスナ)] 要素をキャンバスにドラッグします。

  3. [Transform Message (メッセージの変換)] を探して、[File (ファイル)] の後にドラッグします。

  4. [Salesforce Marketing Cloud] → [Create] を探して、[Transform Message (メッセージの変換)] の後にドラッグします。

  5. [Salesforce Marketing Cloud] の後に [Transform Message (メッセージの変換)] を追加します。

  6. 次は、各要素を設定していきます。[Listener (リスナ)] 要素をダブルクリックします。

    HTTP リスナコンポーネント
  7. [Connector configuration (コネクタ設定)] の横にある プラスボタン をクリックします。

  8. [Host (ホスト)] に「localhost」、[Port (ポート)] に「8081」を指定して、[OK] をクリックします。

  9. [Path (パス)] に「/create」を指定します。

  10. [Create (Salesforce Marketing Cloud)] をダブルクリックします。

    SMC Create の設定
  11. [Connector configuration (コネクタ設定)] の横にある プラスボタン をクリックします。

    SMC user-pass の設定
  12. 必須項目に組織のログイン情報を指定して、[OK] をクリックします。

  13. [Object type (オブジェクト種別)] ドロップダウンから、[List (リスト)] を選択します。

  14. [Transform Message (メッセージの変換)] (Create の前) をダブルクリックして、以下のとおり設定します。

    前のメッセージの変換
  15. [Transform Message (メッセージの変換)] (Create の後) をダブルクリックして、以下のとおり設定します。

    後のメッセージの変換
  16. Mule アプリケーションの作業が完了したら、デプロイできます。

  17. デプロイした後は、使い慣れた REST クライアントを使用して、POST 要求に listName=testlist (curl -d listName=MyName-Test localhost:8081/create など) のパラメータペイロードを指定し、x-www-form-urlencoded to localhost:8081/create に対して実行します。

  18. 結果を正常に取得できるはずです。取得したら、インスタンスに移動してリストが作成されたことを確認します。

注意: 他のエンティティについても同様のフローを使用できますが、Salesforce Marketing Cloud でオブジェクト種別を作成するオブジェクトの名前に変更し、必要に応じてメッセージの変換コンポーネントの項目をマップし直す必要があります。Upload と Delete はまったく同じ方法で設定できるものと思われます。

ユースケース: XML

各自のコードを、以下の完全アプリケーションの XML 表現と比較するとよいでしょう。

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:sfdc-marketing-cloud="http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud"
xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud
http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud/current/mule-sfdc-marketing-cloud.xsd">
	<configuration-properties file="mule-app.properties" />
	<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config">
		<http:listener-connection host="localhost" port="8081" />
	</http:listener-config>
	<sfdc-marketing-cloud:sfdc-marketing-cloud-config name="Salesforce_Marketing_Cloud_Sfdc_marketing_cloud_config" doc:name="Salesforce Marketing Cloud Sfdc marketing cloud config">
		<sfdc-marketing-cloud:basic-connection username="${config.username}" password="${config.password}" authEndPoint="${config.endpoint}" />
	</sfdc-marketing-cloud:sfdc-marketing-cloud-config>
	<flow name="smc-usecase-create-objectFlow">
		<http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/create"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
[{
	ListName: payload.listName
}]]]></ee:set-payload>
			</ee:message>
		</ee:transform>
		<sfdc-marketing-cloud:create doc:name="Create" config-ref="Salesforce_Marketing_Cloud_Sfdc_marketing_cloud_config" objectType="List"/>
		<ee:transform doc:name="Transform Message">
			<ee:message >
				<ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
			</ee:message>
		</ee:transform>
	</flow>
</mule>

既知の問題と制限事項

Salesforce Marketing Cloud コネクタにはいくつかの注意事項があります。複雑な項目の内部のサブクラスを使用して、階層から項目を取得しようとする場合や、自動化オブジェクトを返そうとする場合は、以下のセクションを参照してください。

複雑な項目にサブクラスのデータ型を指定する回避策

Salesforce Marketing Cloud の一定のオブジェクトには基本クラスに属する複雑な項目があります (繰り返し項目など)。こうした特定のケースにおいて、DataSense では基本クラスに固有の項目しか表示できませんが、その基本クラスのサブクラスに属する他の項目を使用したいことがあります。

注意: メッセージの変換コンポーネントの内部に目的の項目を手動で追加すれば、この動作を実行できます。また、サブクラスを使用することを Salesforce Marketing Cloud に知らせ、追加した項目を認識させるために、このサブクラスの名前を値とする文字列型の concreteClassType という特別な項目を追加する必要があります。

「複雑な項目にサブクラスをデータ型として指定」セクションに、この手順を詳述する例が記載されています。

階層からの項目取得は不可

Retrieve 操作では、SQL クエリのようなやり方でレコードを取得できます。

注意: Salesforce Marketing Cloud には、階層内の項目を取得できないという制限があります。

この問題をわかりやすく説明するために、次の例を考えてみます。Subscriber オブジェクトの構造は複雑です。

Subscriber の構造

API では、EmailAddress や SubscriberKey といった第 1 レベルの項目しかクエリできず、Attributes.Name のような項目はクエリできません。

サーバ側の結果に Automation オブジェクトが含まれると例外が発生

Automation オブジェクトで操作 (Create や Delete など) を実行すると、返された結果にも実行した Automation オブジェクトの構造が含まれます。

注意: この場合の問題は、サーバが Automation に isPlatformObject という追加項目を返しますが、WSDL で認識されない点です。

この問題を回避するには、どの操作でも Automation オブジェクトを直接非同期に使用します。操作が非同期の場合は、操作で即時に Operation Queued (操作をキューに追加済み) という応答を受信します。

操作を非同期にする方法についての詳細は、「非同期操作」セクションを参照してください。

一般的なユースケース

Salesforce Marketing Cloud コネクタの一般的なユースケースを以下に示します。

  • Configure Create - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Create を指定した Configure コマンドをコールする。

  • Configure Delete - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Delete を指定した Configure コマンドをコールする。

  • Configure Update - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Update を指定した Configure コマンドをコールする。

  • Create - Marketing Cloud API Web サーバに新しいオブジェクトを作成する。

  • Delete - Marketing Cloud API Web サーバの既存のオブジェクトを削除する。

  • Perform get max count - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に GetMaxCount を指定した Perform コマンドをコールする。

  • Perform start - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Start を指定した Perform コマンドを送信する。

  • Perform stop - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Stop を指定した Perform コマンドを送信する。

  • Retrieve - SQL クエリのような方法で Marketing Cloud API Web サーバからオブジェクトを取得する。

  • Schedule start - Marketing Cloud API SOAP Web サービスに接続した状態で、アクション属性に Start を指定した Schedule コマンドをコールする。

  • Update - Marketing Cloud API Web サーバに存のオブジェクトを更新する。

  • Upsert - オブジェクトが存在しない場合にオブジェクトを作成し、また Marketing Cloud API Web サーバ上に既存のオブジェクトを削除する。この操作を実行するには、Salesforce Marketing Cloud SOAP API の Create メソッドを使用します。

プロキシの追加

プロキシサーバを使用するには、実行時に次のシステムプロパティが設定されている必要があります。

Dhttp.proxyHost =<proxy host>

Dhttp.proxyPort=<proxy port>

プロキシサーバが認証を要求するよう設定されている場合は、次の Java システムプロパティを設定する必要があります。

Dhttp.proxyUser=<proxy user>

Dhttp.proxyPassword=<proxy password>

複雑な項目にサブクラスをデータ型として指定

サブスクライバのリストに毎分メールを送信するように、既存の自動化をスケジュールするとします。

このためには、たとえば、スケジュールに関する詳細を提供するフロー変数を使用して、スケジュール参照をコネクタに入力することが考えられます。

Schedule Start の自動化

メールの送信間隔などの詳細は Recurrence (繰り返し) という項目で指定します。 ScheduleDefinition にある Recurrence 項目は、構造のない複雑な項目の一例です。

Recurrence ではなく、MinutelyRecurrence を使用することを指定するためには、MinutelyRecurrence クラスに属する項目を手動で追加し、サブクラスの名前を値とする文字列型の concreteClassType という特別な項目を追加する必要があります。

以下は、ScheduleDefinition のマッピングがこの例の変数 (vars) でどのように表されるかを示しています。

スケジュールの定義

Recurrence マップに minuteInterval という項目がありますが、この項目は実際には MinutelyRecurrence という Recurrence のサブクラスに属しています。

MinutelyRecurrence オブジェクトを処理していることをコネクタが認識するためには、特別な concreteClassType 項目を追加し、値に MinutelyRecurrence を指定する必要があります。

非同期操作

大半の操作はデフォルトで同期的に行われ、コネクタが操作の結果を待機します。Marketing Cloud API からの操作に関する詳細は、このドキュメントの「関連情報」セクションに記載されている Salesforce Marketing Cloud のメソッドのドキュメントを参照してください。

操作が非同期で行われるよう指定するには、操作の options パラメータを使用する必要があります。ここでは、Create 操作でこの動作を実行する方法の例を示します。他の操作でも同じような方法で実行できます。

この例では、ペイロードに提供される自動化オブジェクトのリストを作成します。 自動化オブジェクトには、この種のオブジェクトを直接処理する操作の結果、未知の項目が存在した場合に例外が生じるという問題があるため、操作を非同期にします。そうすればこの問題を回避できます。

CreateOptions パラメータの役割はコールを非同期にすることです。この例では、変数 (vars) に CreateOptions が指定されています。

Create の自動化

以下は、CreateOptions のマッピングが変数 (vars) でどのように表されるかを示しています。requestType 項目がコールの種別 (SYNCHRONOUS または ASYNCHORONOUS) を判断します。conversationID 項目が非同期コールに一意の ID を割り当てます。

conversationID、callsInConversation、sequenceCode などの項目を使用して非同期コールをグループにまとめることができます (たとえば、サーバに非同期コールを 5 回実行したいが、5 回続けて実行し、実行する順序を指定したい場合は、このすべてに同じ conversationID を指定し、callsInConversation に 5 の値を指定します。これは、このグループはコール数が 5 回で、sequenceCode がこのグループ内のコール順になることを意味します)。

この例では、コールが 1 回であるため、callsInConversation と sequenceCode に 1 の値を渡します。

CreateOptions

Options パラメータにはこの例で示したもの以外にも機能があります。このパラメータの機能についての詳細は、Salesforce Marketing Cloud のオブジェクトに関するドキュメントで、オプションオブジェクト (CreateOptions や DeleteOptions など) を確認してください。

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub