Email Studio での SOAP API の使用
学習の目的
この単元を完了すると、次のことができるようになります。
- SOAP API のメソッド、オブジェクト、エンドポイントを使って作業する。
- Marketing Cloud Engagement で基本的なメールメッセージを構成する。
- 同期処理と非同期処理を使用する状況を認識する。
SOAP API を使用すべき状況
REST API が Marketing Cloud Engagement の多数のアプリケーションに対応するのに対し、SOAP API は Email Studio との連携に特化しています。つまり、メールメッセージのトラッキング情報の作成、送信、取得はすべて SOAP API を使用して実行できます。さらに、この API はアカウント情報の変更も可能にします。
では、Email Studio の操作と Marketing Cloud Engagement での従来の連携について詳しく説明していきます。
SOAP API の基本
SOAP API は OAuth アクセストークンを使用して認証します。以前に説明した内容を覚えていますか? おさらいすると、Marketing Cloud Engagement のユーザー名とパスワードで構成される UsernameToken で認証することもできますが、OAuth トークンを使うと接続の安全性が高まります。
SOAP API はまた、WSDL とエンドポイントの両方にテナント固有のエンドポイントを使用します。これらのリンクを使用して、付属のメソッドやオブジェクトを操作することができます。既存の実装で作業している場合のために Marketing Cloud Engagement には従来のエンドポイントもありますが、新規の開発には新しいエンドポイントを使用することをお勧めします。
メソッドとオブジェクト
Marketing Cloud Engagement には要求で使用できる数種類のメソッドが用意されています。要求は、アカウント、メール、所有者などのさまざまなオブジェクトでこれらのメソッドを使用します。使用可能なオブジェクトやプロパティの完全リストについては、WSDL ファイルまたは「Salesforce開発者」を参照してください。予告しておきますが、膨大な数に上ります! ここでその一部をご紹介します。
メソッド名 |
目的 |
---|---|
Configure |
Marketing Cloud Engagement アカウントを構成する。 |
Create |
1 つ以上のオブジェクトを作成する。 |
Delete |
1 つ以上のオブジェクトを削除する。 |
Describe |
オブジェクトのメタデータを取得する。 |
Execute |
1 つ以上のヘルパー関数にアクセスして実行する。 |
Extract |
Marketing Cloud Engagement の FTP サイトにファイルを抽出する。 |
GetSystemStatus |
Marketing Cloud Engagement アカウントのステータスを取得する。 |
Perform |
非同期アクションを実行する。 |
Query |
Marketing Cloud Engagement データをクエリする。 |
Retrieve |
1 つのオブジェクトタイプに関する情報を取得する。 |
Schedule |
実施するアクションまたはイベントをスケジュールする。 |
Update |
1 つ以上のオブジェクトの情報を更新する。 |
SOAP API の使用
SOAP API を使用するときは、次の点に留意します。
- 要求の同期処理に要する時間は 3 秒 (1 回のメール送信の場合) から 30 秒 (トラッキングデータを取得する場合) の間と予測されます。
- 各要求が次の 3 つのステータスのいずれかを返します。
OK
エラーがあり
エラー
- Marketing Cloud Engagement はデータ値を中部標準時 (CST) で保存します (夏時間は考慮されません)。日付情報を取得したときに、その情報がシステム向けに最適化されるようにする場合は、協定世界時 (UTC) とのオフセットを使用することができます。
- 送信先のカルチャーコードに基づいて、メールメッセージに異なる文字セットを設定できるため、これらのメッセージをテストして、すべての文字が正しく表示されることを確認することをお勧めします。
例: メールメッセージの作成
SOAP API の一般的なタスクをいくつか見てみましょう。次の C# の例は、シンプルなメールの作成方法を示しています。コードが件名行とコンテンツ、識別する名前と場所を割り当てているため、Marketing Cloud Engagement アカウントで簡単に見つけることができます。
Email email = new Email(); email.Subject = "Check out my way cool email"; email.Name = "Dynamic Email_" + DateTime.Now.ToShortTimeString(); email.HTMLBody = "<center>##Way Cool Email</center>"; email.TextBody = "Way Cool Email"; email.CharacterSet = "iso-8859-1"; email.CategoryID = 556442; //This is the Folder where the email is stored. email.CategoryIDSpecified = true; CreateResult[] results = proxy.Create(new CreateOptions(), new APIObject[] { email }, out requestID, out status);
C# の次の例は、メール送信定義を使用してメールメッセージを送信する 1 つの方法を示しています。この送信定義には、メール送信と送信のその他の詳細を特定するために必要な情報が含まれています。
// 1. Create the EmailSendDefinition EmailSendDefinition sd = new EmailSendDefinition(); sd.CustomerKey = "95"; // 2. Start the Send PerformResult[] results = integrationFramework.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { sd }, out status, out message, out requestID); // 3. Print out overall results System.Text.StringBuilder sb = new System.Text.StringBuilder(); sb.Append("Perform Send Definition"); sb.AppendFormat("\nOverall result: {0}. RequestID: {1}, {2}\n{3}\n{4}\n{5}\nTaskID: {6}", status, requestID, message, results[0].ErrorCode, results[0].StatusCode, results[0].StatusMessage, results[0].Task.ID); Console.WriteLine(sb.ToString());
送信が完了したら、このサンプルコードを使用して、送信のトラッキング情報を取得できます(元の送信後に返された JobID を含める必要があります)。
/** *Returns details of send - when you send email, it returns JobID. *Use returned ID to get details. */ public void testSendDetails() { RetrieveRequest retrieveRequest = new RetrieveRequest(); retrieveRequest.ObjectType = "Send"; String[] props = { "SentDate", "UniqueOpens", "NumberSent", "NumberDelivered", "HardBounces", "SoftBounces" }; retrieveRequest.Properties =props; /** * Use date range to get all sends that happened in range */ /** SimpleFilterPart filter = new SimpleFilterPart(); filter.Property = "SendDate"; filter.SimpleOperator = SimpleOperators.greaterThanOrEqual; filter.DateValue = new DateTime[1]; filter.DateValue[0] = DateTime.Now; retrieveRequest.Filter = filter; */ /** * Details for the particular job */ SimpleFilterPart filter = new SimpleFilterPart(); filter.Property = "ID"; filter.SimpleOperator = SimpleOperators.equals; filter.Value= new string[] {"12043295"}; retrieveRequest.Filter = filter; /** * If this job happened from Child Account include ClientId in request. */ /* ClientID id = new ClientID(); id.ID = 90554; id.IDSpecified = true; retrieveRequest.ClientIDs = new ClientID[] {id}; */ APIObject[] results = null; String requestId = null; String response = soapClient.Retrieve(retrieveRequest, out requestId, out results); Send send = null; if (response != null && response.ToLower().Equals("ok")) { if (results != null) { send = (Send) results[0]; } } Assert.IsNotNull(send); }
ほとんどの API オブジェクトは、結果を 2,500 件のバッチで返します。要求でレコード数を減らすよう求めることもできれば、2,500 件超の結果を取得するために追加の要求を実行することもできます。
同期処理と非同期処理
要求を同期操作または非同期操作として実行することを選択できます。同期要求では、すぐに結果が返されます。SOAP API は非同期要求をキューに配置して、サービスが使用不能になってもコールが失われないようにします。SOAP API に対する要求に回復力をもたせるために、非同期処理を使用します。この方法では、システムが停止した場合に要求が中断しないようにする対策として要求がキューに配置され、パフォーマンスの確実性が高まります。また、同期 API スレッドの実行数を要求ごとに 20 回以下にすることをお勧めします。これらの要求には、1 回の同期コールにつき最大 50 のオブジェクト、1 回の非同期コールにつき最大 100 のオブジェクトの参照を含めます。
最後の単元に進みましょう。次は、API 連携を最大限に活用するためのエキスパートのヒントやリソースを紹介します。