Salesforce の追加設定 v10.2 - Mule 4
このトピックを参照して、Salesforce 用 Anypoint Connector (Salesforce Connector) の追加設定や使用方法を確認してください。
カスタムイベント通知
Salesforce Connector を使用すると、カスタムイベント通知を取得できます。これらの通知は、Salesforce データの変更とは関係のない一般的なイベントに適用されます。
カスタムイベント通知を取得する手順は、次のとおりです。
-
Publish streaming channel 操作を使用して、ストリーミングチャネルを作成します。
StreamingChannel は Salesforce の特殊なオブジェクトで、汎用のストリーミング API イベントをリスナーに通知するために使用するチャネルを表します。
Salesforce またはワークベンチを使用してストリーミングチャネルを作成することもできます。
-
Subscribe channel listener 操作を使用して、チャネルをサブスクライブします。
Salesforce Connector は、ストリーミングチャネルのカスタムイベントを Mule イベントに変換します。
ストリーミングチャネルの操作についての詳細は、「Salesforce からデータを受信するストリーミングチャネルの作成」および「Salesforce からのデータの受信」を参照してください。
イベントとトピック
アプリケーションは、既存の Salesforce トピックをサブスクライブするか、新しいトピックを作成してサブスクライブすることでイベントを受信できます。
フローを通過する各イベントには、変更された Salesforce データに関する情報 (データがいつどのように変更されたのかなど) が含まれています。
Salesforce は、イベントを 24 時間保存します。トピックまたはチャネルへのサブスクライバーは、24 時間の保持期間中にそのトピックまたはチャネルに関連するイベントを取得できます。保持期間が終了すると、サブスクライバーは、まだ有効期限が切れていない新しいイベントを取得できます。
Salesforce は、各ブロードキャストイベントに数値の ID を割り当てます。ID は増分されますが、必ずしも連続するイベントごとに 1 つずつ増分するとは限りません。たとえば、ID 999 のイベントに続くイベントの ID は 1025 になる可能性があります。ブロードキャストイベント ID は組織とチャネルで一意です。Salesforce は、削除されたイベントの ID を再利用しません。
Salesforce からアプリケーションへのデータのストリーミング時のイベントの処理については、「Salesforce からのデータの受信」を参照してください。
トピックのイベントの受信
トピックに関連付けられている Salesforce の変更に関するイベントを受信できるようにするには、事前にトピックを作成する必要があります (存在しない場合)。トピックを作成すると、コネクタによって PushTopic が作成されます。PushTopic は Salesforce の特殊なオブジェクトで、名前 (この場合はトピックの名前) と Salesforce Object Query Language (SOQL) クエリを一緒にバインドします。トピックを作成したら、そのトピックを名前でサブスクライブできます。
Create (create) または Publish topic (publish-topic) 操作を使用して、トピックを作成できます。次の例では、publish-topic 操作を使用して、トピックを作成します。
<sfdc:publish-topic name="AccountUpdates" query="SELECT Id, Name FROM Account"/>
または、Salesforce で、システムログからアクセス可能な [Enter Apex Code (Apex コードの入力)] ウィンドウで次のようなコードを実行して、トピックを作成することも可能です。
PushTopic pushTopic = new PushTopic();
pushTopic.ApiVersion = 23.0;
pushTopic.Name = 'AllAccounts';
pushTopic.Description = 'All records for the Account object';
pushTopic.Query = 'SELECT Id, Name FROM Account';
insert pushTopic;
System.debug('Created new PushTopic: '+ pushTopic.Id);Subscribe to a Topic
トピックをサブスクライブするには、Subscribe topic listener (subscribe-topic-listener) または Replay topic listener (replay-topic-listener) をフローの入力元として追加します。入力元はインバウンドエンドポイントとして機能します。サブスクリプションがイベントを受信するたびに、入力元が Mule アプリケーションのフローの残りの部分を実行します。
次の XML の例では、AccountUpdates トピックがイベントを受信すると、Mule が INFO レベルのメッセージをログに出力します。
<flow name="accountUpdatesSubscription">
<!-- INBOUND ENDPOINT -->
<sfdc:subscribe-topic-listener topic="AccountUpdates"/>
<!-- REST OF YOUR FLOW -->
<logger level="INFO" message="Received an event for Salesforce Object ID #[map-payload:Id]"/>
</flow>過去に Salesforce でパブリッシュされていないトピックをサブスクライブできます。ただし、トピックがパブリッシュされた場合、再度サブスクライブしないと、そのトピックに関する通知を受信しなくなります。
Replay a Topic
サブスクライバーは、どのイベントを受信するか指定できます。デフォルトでは、サブスクライバーはサブスクライブ後に発生したイベントのみを受信します。イベントは 24 時間の保管期間を過ぎると破棄されます。
Replay Topic Listener 操作には次のオプションがあります。
-
ALLサブスクライバーは、24 時間の保持期間内の過去のイベントと、クライアントがサブスクライブした後に送信された新規イベントを含め、すべてのイベントを受信します。
-
ONLY_NEWサブスクライバーが、クライアントのサブスクライブ後にブロードキャストされた新規イベントを受信します。
-
FROM_REPLAY_IDサブスクライバーが、指定したイベント
replayId より後のすべてのイベントを受信します。
ALL または ONLY_NEW 再生オプションを指定すると、replayId の値は無視されます。
Studio では、[Resume from the Last Replay Id (最後の再生 ID から再開)] チェックボックスにより、コネクタが最後に処理したイベントの再生 ID に基づいて、保存されているイベントの自動再生を指定できます。この機能は、サーバーのシャットダウンや接続の切断などでコネクタのリスンが中断しているときに使用できます。保存された再生 ID が 24 時間の保持期間を経過している場合は、再生オプションがどのイベントを再生するかを決定します。
次の XML の例では、Replay topic listener がロガーコンポーネントメッセージのインバウンドエンドポイントのように機能します。
<flow name="accountUpdatesReplay">
<!-- INBOUND ENDPOINT -->
<sfdc:replay-topic-listener topic="AccountUpdates" replayId="1" replayOption="ALL" autoReplay="true"/>
<!-- REST OF YOUR FLOW -->
<logger level="INFO" message="Replayed events: #[payload]"/>
</flow>Salesforce へのデータの転送
Salesforce Connector は、データを Salesforce に転送するフローのアウトバウンドコネクタとして使用できます。コネクタをこの用途で使用する場合は、Salesforce Connector をフローのインバウンドエンドポイントの右側に配置します。
Salesforce からのデータの受信
Salesforce Connector をインバウンドコネクタとして使用すれば、Salesforce からアプリケーションにデータをストリーミングできます。コネクタをこの用途で使用する場合は、次のいずれかの入力元を使用します。
-
Subscribe topic listener
-
Subscribe channel listener
-
Replay topic listener
-
Replay channel listener
コネクタは、Salesforce ストリーミング API からの通知をリスンする Salesforce ストリーミングモードに自動的に変換されます。
この例では、Salesforce Connector がトピックに関する通知をリスンして、データをフローにフィードします。
ストリーミングチャネルからサブスクライバーに送信される通知は、レコードベースのイベントに限定されません。Salesforce Connector を使用して、Salesforce のストリーミングチャネルを操作できます。
ストリーミングチャネルについての詳細は、「Salesforce ストリーミング API」を参照してください。
Salesforce からデータを受信するストリーミングチャネルの作成
ストリーミングチャネルを作成するには、組織で適切な Salesforce ストリーミング API 権限が有効になっている必要があります。
ストリーミングチャネルを作成する手順は、次のとおりです。
-
Salesforce Developer Edition 組織にログインします。
-
[すべてのタブ] (+) で、[ストリーミングチャネル] を選択します。
-
[ストリーミングチャネル] タブで、[新規] を選択して新しいストリーミングチャネルを作成します。
-
[ストリーミングチャネル名] 項目に
/u/notifications/ExampleUserChannel と入力します。 -
説明 (省略可能) を入力します。
コネクタの Create 操作または Publish streaming channel (publish-streaming-channel) 操作を使用して、ストリーミングチャネルを作成することもできます。次の例では、publish-streaming-channel 操作を使用します。
<sfdc:publish-streaming-channel
name="/u/Notifications"
description="General notifications"/>ストリーミングチャネルのサブスクライブ
ストリーミングチャネルを作成した後にそのチャネルをサブスクライブすれば、イベントの受信を開始できます。subscribe-channel-listener 入力元はインバウンドエンドポイントのように機能します。この例では、/u/TestStreaming のサブスクリプションがイベントを受信するたびに、フローの残りの部分を実行し、メッセージを INFO レベルで記録します。
<flow name="notificationsChannelSubscription">
<!-- INBOUND ENDPOINT -->
<sfdc:subscribe-channel-listener streamingChannel="/u/TestStreaming"/>
<!-- REST OF YOUR FLOW -->
<logger level="INFO" message="Received an event: #[payload]"/>
</flow>Salesforce 環境で使用可能な変更イベントは、Salesforce API で提供されないため、Subscribe channel listener 操作の [Streaming channel (ストリーミングチャネル)] 項目には表示されません。ただし、コネクタはストリーミングチャネルをサブスクライブしてこの情報を取得できます。たとえば、All Change Events チャネルをサブスクライブするには、サブスクライブするチャネル名として /data/ChangeEvents を使用できます。
詳細は、『Salesforce Change Data Capture Developer Guide (Salesforce 変更データ取得開発者ガイド)』の「Subscription Channels (サブスクリプションチャネル)」を参照してください。
チャネルのインバウンドプロパティのストリーミング
次の情報がインバウンドプロパティとして渡されます。
-
channel - Channel JSON プロパティにマップします。 -
type - データの Type JSON プロパティにマップします。 -
createdDate - データの createdDate JSON プロパティにマップします。
channel を除き、イベント内の各プロパティは、INBOUND プロパティとして使用できます。
ストリーミングチャネルからのイベントの再生
ストリーミングチャネルは、通知を再生できます。replay-channel-listener 入力元はインバウンドエンドポイントとして機能します。次の例のように使用できます。
<flow name="flowStreamingChannelReplay">
<!-- INBOUND ENDPOINT -->
<sfdc:replay-channel-listener streamingChannel="/u/Notifications" replayId="1" replayOption="ALL"/>
<!-- REST OF YOUR FLOW -->
<logger level="INFO" message="Replayed events: #[payload]"/>
</flow>ALL または ONLY_NEW 再生オプションを指定すると、replayId の値は無視されます。
ストリーミングチャネルへのイベントの転送
Salesforce では、REST API を使用してカスタムイベントを特定のストリーミングチャネルに転送できます。これを行うには、ワークベンチまたはこのコネクタを使用します。
次の例では、コネクタの push-generic-event 操作を使用して、カスタムイベントを ID 0M6j0000000KyjBCAS のチャネルに転送します。
<flow name="flowPushGenericEvent">
<!-- INBOUND ENDPOINT -->
<sfdc:push-generic-event channelId="0M6j0000000KyjBCAS">
<sfdc:events>
<sfdc:event payload="Notification message text"/>
</sfdc:events>
</sfdc:push-generic-event>
<logger level="INFO" message="Replayed events: #[payload]"/>
</flow>チャネル ID は、publish-streaming-channel 操作の応答マップから取得できます。または、Salesforce ページからチャネル ID を取得することもできます。
-
Developer Edition 組織にログインします。
-
[すべてのタブ] (+) で、[ストリーミングチャネル] を選択します。
チャネルリストにチャネル ID 項目が表示されていない場合は、次の手順を実行します。
-
[Create New View (新規ビューの作成)] をクリックします。
-
[Name (名前)] 入力項目にビューの名前を入力します。
-
[Available Fields (選択可能な項目)] リストで、[Streaming Channel ID (ストリーミングチャネル ID)] を選択し、[Add (追加)] をクリックします。
リストに各ストリーミングチャネルの ID が表示されるはずです。
-
他の項目を追加します。
-
[Save (保存)] をクリックします。
push event 操作から応答として受信した JSON は次のようになります。
[
{
"userOnlineStatus": {
},
"fanoutCount": 0
}
]データのバッチ読み込み
Salesforce Bulk API は、組織のデータのバッチを Salesforce に読み込みます。Salesforce Connector には、Bulk API と連動する Create 操作と Create Bulk 操作が用意されています。
一括操作はすべて、Salesforce が作成プロセスをバックグラウンドで処理します。コネクタは BatchInfo オブジェクトで応答します。このオブジェクトにはバッチの ID と、バッチオブジェクトをアップロードするために作成するジョブの ID が含まれます。
Salesforce で、一括データ読み込みジョブのジョブ ID を使用して、一括データ読み込みジョブと関連するバッチの状況を追跡できます。
-
YOUR_NAME > [Setup (設定)] > [Monitoring (監視)] > [Bulk Data Load Jobs (一括データ読み込みジョブ)] をクリックします。
-
ジョブ ID をクリックすると、ジョブの詳細ページが表示されます。
ジョブの詳細ページに、ジョブに関連する全バッチのリストが表示されます。リストには、各バッチの [View Request (要求を表示)] および [View Response (応答を参照)] リンクが表示されます。バッチが CSV ファイルの場合は、これらのリンクから CSV 形式の要求や応答が返されます。バッチが XML ファイルの場合は、これらのリンクから XML 形式の要求や応答が返されます。
リード取引開始要求 ID
LeadConvertRequest 操作でリード ID を指定するには、DataWeave transform message を使用します。操作の前で transform message を使用するには、操作のメタデータで指定されないため leadId 項目を追加する必要があります。
<ee:transform doc:name="Transform Message" >
<ee:message >
<ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
{
leadId: "LEAD_ID",
accountId: "ACCOUNT_ID",
convertedStatus: "Closed - Converted",
doNotCreateOpportunity: true
} as Object {
class : "org.mule.extension.salesforce.api.core.LeadConvertRequest"
}]]></ee:set-payload>
</ee:message>
</ee:transform>オブジェクトストアの使用法
Salesforce Connector と Mule の両方で、オブジェクトストアを使用して自動的なメッセージの返信やメッセージの再配信などの機能に関するデータを保持します。
-
オンプレミスで実行される Mule アプリケーションでは、トランザクション制限のない Mule Object Store を使用します。
-
CloudHub デプロイメントがある Mule アプリケーションでは Object Store v2 を使用します。
Object Store v2 の無料バージョンには 1 秒あたり 10 件のトランザクションの制限があります。
オブジェクトストアのバージョンについての詳細は、「Object Store Notes (オブジェクトストアに関するメモ)」を参照してください。
Replay Topic 操作と Replay Channel Listener 操作
Replay topic 操作と Replay channel listener 操作には、アプリケーションを再起動する前に受信した最新の再生 ID から続行するオプションがあります。
Mule アプリケーションを初めて起動すると、コネクタによって正常に処理されたメッセージまたは失敗したメッセージに関連するデータを保存するために使用されるオブジェクトストアが作成されます。
-
正常に処理された各メッセージでは、保存される情報はメッセージに関連付けられた再生 ID です。
-
失敗した各メッセージでは、保存される情報は処理に失敗した最小の再生 ID を表す番号です。
これらの 2 つの構造により、メッセージが 2 回処理されることがなく、アプリケーションを再起動したときに、失敗したメッセージを再処理することができます。
コネクタがサブスクライブされているトピックまたはストリーミングチャネルを通じてメッセージが送信されるたびに、コネクタでは最大 4 つのトランザクションを使用してオブジェクトストア情報が更新されます。
OAuth 2.0 接続種別
OAuth 2.0 接続を設定するときに、各リソースの所有者の ID データを保存するオブジェクトストアを指定できます。オブジェクトストアを指定しない場合、Mule が自動的にデフォルトのオブジェクトストアをプロビジョニングします。
アプリケーションは新しいリソース所有者が認証されると自動的にオブジェクトストアとやり取りし、アクセストークンが更新されるか、アクセストークンが無効化されます。
入力元のメッセージ再配信
最初の失敗後の再配信の試行回数を設定することで、入力元の再配信ポリシーを設定できます。このポリシー用のオブジェクトストアを指定できます。オブジェクトストアを指定しない場合、Mule が非永続的なオブジェクトストアを作成します。
オブジェクトストアとやり取りするために使用されるトランザクションの数は、再配信ポリシーで設定した再試行回数に基づいて変動します。
再配信ポリシーの設定についての詳細は、「再配信ポリシー」を参照してください。
使用上の注意
Upsert
更新/挿入しようとしている sObject に外部 ID 項目名を設定しなければ、Upsert 操作に失敗します。
sObject priceBookentry2 では Upsert 操作が機能しません。
bulk upsert の contentType の値は変更できませんが、Create job 操作を使用して、コンテンツタイプを CSV または圧縮 CSV (最大文字数近くに達した場合) のいずれかに設定できます。Create batch 操作でフォローアップします。
Query
DataSense を介して sObject の項目と対応するデータ型を表示することはできますが、Query 操作はすべての項目を String で返します。
実際のデータ型を使用するには、Transform または Transform Message コンポーネントを使用して、項目を目的の型に変換します。
CreatedDate 項目は dateTime として表示されますが、クエリは日付を表す String 値を返します。項目を dateTime として使用するには、Transform Message コンポーネントを使用して設定します。
Date 項目と dateTime 項目を保存するには、DataWeave 式を使用して Date および Calendar Java オブジェクトを作成します。
Invoke APEX Rest Method
Invoke APEX Rest 操作を使用すると、ユーザーは REST サービスとして公開されている Apex クラスからメソッドを呼び出すことができます。次の例は、この操作のペイロードを示しています。
<ee:transform doc:name="Transform Message">
<ee:message >
<ee:set-payload ><![CDATA[output application/java
---
{
body: {
URLParameters: {
Parameter1: "parameter1Value",
Parameter2: "parameter2Value"
},
account: {
Name: "Example",
AccountNumber: "55"
}
},
headers: {
header1:"header1Value"
},
cookies: {
cookie1:"cookie1Value"
},
queryParameters: {
queryParam1Name:"queryParam1Value",
queryParam2Name:"queryParam2Value"
}
}]]></ee:set-payload>
</ee:message>
</ee:transform>例について説明します。
-
body 要素に含まれるURLParameters は、Apex クラスに記述されている REST リソースのパス内のワイルドカードを置き換えるパラメーターが含まれるマップです。たとえば、REST リソースが
@RestResource(urlMapping='/myResource/*/mySubResource/*') に設定されている場合、Parameter1 の値で 1 番目の* が置き換えられ、Parameter2 の値で 2 番目の* が置き換えられます。 -
キー名は
Parameter で始まり、その後に、置き換える* の位置を示す数値が続く必要があります。 -
URLParameters ブロックの後に、REST リソースに送信するbody 値のコンテンツを指定します (例のaccount ブロックを参照)。 -
headers およびcookies 項目では、HTTP 要求と共に目的のサービスに渡すヘッダーと Cookie を記述します。 -
queryParameters 項目では、使用するクエリパラメーターのほか、指定した Apex クラスで受け入れられる必要があるこのマップ内のキーと値を記述します。
Salesforce Connector リストへの値の挿入
Salesforce Connector の既存のリストに連動値を挿入しても、必ずしも機能するとは限りません。この機能をテストして確認します。
Salesforce リストの値の照合
Salesforce の既存のリスト項目の値と照合する場合は、リストとまったく同じ値を使用します。たとえば、「US」という値を使用して、「USA」という値を含むリストのコンテンツと照合した場合、照合は機能しますが、結果としてリストに「US」と「USA」の 2 つの値が表示されます。