【第161回】 REST API を使用して新規データエクステンションを作成する

Salesforce Marketing Cloud の Summer '24 リリースで、データエクステンションを操作する Custom Object REST API がリリースされました。

これまで Marketing Cloud でデータエクステンションを操作する際は、SOAP API や SSJS により行われてきましたが、今後は REST API により、手軽にかつ、高速にデータエクステンションの操作ができるようになったわけです。

あくまで目安になりますが、フィールドが 100 項目存在するデータエクステンションを作るのに、SSJS で作成すると 1 分程度かかりましたが、REST API であれば、3 秒程度で作成できました。

---

以下のヘルプドキュメントに、Salesforce 側が提示する「ユースケース」が掲載されていますので、確認してみて下さい。

Custom Objects | Marketing Cloud Engagement APIs and SDKs | Salesforce Developers

Data Extension Data | Marketing Cloud Engagement APIs and Programmatic Languages | Salesforce Developers

---

早速、私の方で、最も使用する頻度が高いであろう「新規データエクステンションの作成」を試してみましたのでレポートしてみます。

今回の記事では REST API を使用します。過去の記事「Salesforce Marketing Cloud で REST API を叩いてみよう」の Part.1 と Part.2 の記事で取得できる以下の 2 つが必要となりますので、事前に用意してください。

■ Part.1 の REST ベース URL
■ Part.2 の アクセストークン

以下のスコープが API セットアップで選択されている必要があります。
■ DATA - Data Extensions - Write
（※今回の例の「新規データエクステンション作成」の場合です）

REST API Permission IDs and Scopes | Marketing Cloud Engagement APIs and SDKs | Salesforce Developers

---

それでは説明に入ります。

データエクステンションの作成を考える時は、送信可能データエクステンションであるか、送信不可データエクステンションであるかを区別しておく必要があります。以下のように分かれます。

--- メソッド 
POST 

--- エンドポイント
[REST ベース URL].rest.marketingcloudapis.com/data/v1/customobjects

--- ヘッダー 
Content-Type：application/json 
Authorization：Bearer [アクセストークン] 

■ 送信可能データエクステンションの Body サンプル

{
  "name": "NewDE_Sendable",
  "key": "",
  "isSendable": true,
  "sendableCustomObjectField": "Text",
  "sendableSubscriberField": "_SubscriberKey",
  "categoryId": 93800,
  "fields": [

{ "name" : "Text", "type" : "Text" , "length" : 50 , "ordinal" : 1 , "IsPrimaryKey" : true ,"isNullable" : false ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "EmailAddress", "type" : "EmailAddress" , "length" : 254 , "ordinal" : 2 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Number", "type" : "Number" , "ordinal" : 3 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Date", "type" : "Date" , "ordinal" : 4 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Boolean", "type" : "Boolean" , "ordinal" : 5 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Phone", "type" : "Phone" , "ordinal" : 6 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Decimal", "type" : "Decimal" , "length" : 25 , "scale" : 1 , "ordinal" : 7 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Locale", "type" : "Locale" , "ordinal" : 8 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false}
    
  ]
}

■ 送信不可データエクステンションの Body サンプル

{
  "name": "NewDE_Not_Sendable",
  "key": "",
  "categoryId": 93800,
  "fields": [

{ "name" : "Text", "type" : "Text" , "length" : 50 , "ordinal" : 1 , "IsPrimaryKey" : true ,"isNullable" : false ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "EmailAddress", "type" : "EmailAddress" , "length" : 254 , "ordinal" : 2 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Number", "type" : "Number" , "ordinal" : 3 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Date", "type" : "Date" , "ordinal" : 4 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Boolean", "type" : "Boolean" , "ordinal" : 5 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Phone", "type" : "Phone" , "ordinal" : 6 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Decimal", "type" : "Decimal" , "length" : 25 , "scale" : 1 , "ordinal" : 7 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false},
{ "name" : "Locale", "type" : "Locale" , "ordinal" : 8 , "IsPrimaryKey" : false ,"isNullable" : true ,"isTemplateField": false, "isInheritable": true, "isOverridable": true, "isHidden": false, "isReadOnly": false, "mustOverride": false}
    
  ]
}

ここでの注意点は、以下です。

■ 最初の name は、新規のデータエクステンション名です。
■ key は必須ですが、ブランクにすることで、ランダムキーとなります。
■ categoryId とは、格納先のフォルダの ID のことです。
■ プライマリーキーの項目は、必須項目である必要があります。
■ sendableCustomObjectField はご自身の送信キーに変更して下さい。
■ sendableSubscriberField は "_SubscriberKey" 固定となります。
■ isTemplateField 以降の項目は、必須項目であり、変更不要です。
■ 大文字・小文字は厳密に区別されます。

---

categoryId（フォルダ ID）の探し方ですが、そのフォルダに格納されているデータエクステンションを何でも良いので開きます。左上の「パンくず」部分がリンクになっているので、categoryId を調べたいフォルダを開きます。

すると、URL に categoryId が掲載されています。下記の場合 93800 です。

【注意】
存在しない categoryId を指定しまうと、そのデータエクステンションにたどり着けなくなり、作成したデータエクステンションに一切アクセスできなくなります。（※アクセスできる方法をご存知の方はコメントまで！）

---

また当然、データ保持ポリシーなども設定可能ですので、詳しくは下記リンクを参照して設定してみて下さい。私の Body サンプルは、シンプルにするためにそれらを敢えて除外してあります。

Custom Objects | Marketing Cloud Engagement APIs and SDKs | Salesforce Developers

---

★★★ Excel ツール (ダウンロード) ★★★

なお、私の方で Field の部分を簡単に作成できるように、加工用のエクセルを作成しましたので、そちらをご活用ください。エクセルに記載後、「H」列の「Copy & Paste」をテンプレートに貼り付けるだけで、簡単にデータエクステンションが作成できます。

DE_creation_REST_API_Nobuyuki_Watanabe.xlsx

12.5 KB

ファイルダウンロードについて

ダウンロード

※最終フィールドの最後に付いている「,」（カンマ）は、貼り付け後に手動で削除して下さい。エラーの原因となります。

■ 送信可能データエクステンションのテンプレート

{
  "name": "NewDE_Sendable",
  "key": "",
  "isSendable": true,
  "sendableCustomObjectField": "XXXXX",
  "sendableSubscriberField": "_SubscriberKey",
  "categoryId": XXXXX,
  "fields": [

Copy & Paste

  ]
}

■ 送信不可データエクステンションのテンプレート

{
  "name": "NewDE_Not_Sendable",
  "key": "",
  "categoryId": XXXXX,
  "fields": [

Copy & Paste

  ]
}

---

先日、データエクステンションでレコードの値を取得する例について、質問がありましたので、私が試したサンプルを記載しておきます。

データエクステンションのデータを取得

Data Extension Data | Marketing Cloud Engagement APIs and Programmatic Languages | Salesforce Developers

以下のスコープが API セットアップで選択されている必要があります。
■ DATA - Data Extensions - Read
（※「データエクステンションのデータを取得」の場合です）

--- メソッド 
GET

--- エンドポイント
[REST ベース URL].rest.marketingcloudapis.com/data/v1/customobjectdata/key/XXXXXXXXXXXXXXX/rowset?$filter=XXX_Flag%20eq%20'True'

--- ヘッダー 
Authorization：Bearer [アクセストークン] 

上記の例は、フィールド名が「XXX_Flag」でブール値が「True」であるものを、パラメーターで「?$filter=XXX_Flag%20eq%20'True'」を指定して取得する例になります。

・メソッドは GET になりますので、ボディは不要です。

・「XXXXXXXXXXXXXXX」には、データエクステンションの外部キーを入力して下さい。

・1 ページにつき、2500 レコードまで取得できます。（ページの切り替えは、パラメーターに「?$page=2」で処理できます。）

・フィルタリング、ソート、ページングは送信可能なデータエクステンションでのみサポートされています。

・送信不可データエクステンションからデータを取得するリクエストは、最大 200 行まで返すことができます。

・エンドポイントで使用する「フィルター演算子」は下記のリンクを参照して下さい。

Assets | Marketing Cloud Engagement APIs and Programmatic Languages | Salesforce Developers

---

いかがでしたでしょうか？

これまで私は SSJS（スクリプトアクティビティ）を使って、項目数の多いデータエクステンションを作成してきました。果たして、この REST API によるデータエクステンションの新規作成機能は、それを代替するものになるでしょうか？

SSJS（スクリプトアクティビティ）を使って新規データエクステンションを作成する方法に関して、質問を頂きましたので、記事にしました。

スクリプトアクティビティを使用するメリットとしては、スクリプトアクティビティにスクリプトを証跡として残せることであると感じています。一方で REST API は手軽ですが、コードを使い捨てるか、エクセルやメモ帳などで管理する必要がありそうです。

ともあれ、REST API でデータエクステンションを扱えるということは他にもメリットが盛り沢山だと思いますので、素晴らしい機能追加だと思います。

今回は以上です。

Click here for English version

SFMC Tips #44 : Creating a New Data Extension Using the REST API

次の記事はこちら

前回の記事はこちら

私の note のトップページはこちら

Nobuyuki Watanabe｜note