【第244回】 REST API を使ってインポート定義無しのインポートを実行する

Salesforce Marketing Cloud の 2024 年の Spring '24 新機能リリースでは、Automation に関する様々な REST API ルートが導入されました。この新たなルートを利用することで、インポート定義を事前に作成する必要なく、単回使用のデータエクステンションへのデータインポートが可能になります。

主な特徴とメリット

この機能を活用することで、以下の外部ストレージに保存されたデータを、オートメーションの定義を設定せずに、データエクステンションへ簡単にインポートできます。

• Amazon S3

• Google Cloud Storage

• Microsoft Azure Blob Storage

• 外部の SFTP

運用効率を大幅に向上

この新しいルートは、頻繁に複数のファイルを追加・更新する必要があるケースで非常に有効です。例えば、以下のような差分のファイルがある場合、ファイル名を変えるだけで迅速にインポートを実行できるため、運用の効率化が期待できます。

TransactionData_20250301.csv
TransactionData_20250302.csv
TransactionData_20250303.csv
TransactionData_20250304.csv
TransactionData_20250305.csv
TransactionData_20250306.csv
TransactionData_20250307.csv
TransactionData_20250308.csv
TransactionData_20250309.csv
TransactionData_20250310.csv
・・・（続く）

この連続インポートを実行した場合、すべてのリクエストが順次処理され、前のインポートが実行中であっても、エラーになりません。未処理のリクエストはキューに保持され、その後取り込まれます。

私の体感ですが、1 ヶ月分（30 ファイル）を連続でインポートした場合、5 分程度で完了しました。驚くべき作業の効率化ですね。

Spring '25 リリースでの拡張機能

Spring '25 新機能リリースでは、この API を使って、キータイプ「非対称」を用いた暗号化ファイルのインポートが可能になりました。

これにより、データエクステンションにインポートする前にファイルを転送して暗号化解除する必要がなくなります。インポート作業が一層柔軟になりますね。

では次に、REST API ルートを使用した単回インポートを実行する方法について解説します。

事前準備

REST API の設定方法

それでは、Talend API Tester や Postman で、以下の設定を行ってください。

--- メソッド 
POST 

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

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

以下のリクエストボディを使用して、CSV ファイルを特定のデータエクステンションにインポートします。以下はサンプルデータです。

{
    "source": {
        "fileInfo": {
            "specifier": "TransactionData_20250301.csv",
            "contentType": "CSV",
            "hasMultipleFiles": false,
            "standardQuotedStrings": true
        }
    },
    "target": {
        "type": "DataExtension",
        "key": "8082AA4B-6E2E-4E93-95AA-2A16B8FB6A88",
        "updateType": "AddAndUpdate"
    },
    "mapping": {
        "allowErrors": true,
        "fieldMappingType": "InferFromColumnHeadings"
    },
    "transport": {
        "key": "1DA6211C-1EFE-4F50-82E3-32118B40ACFB"
    }
}

各項目の詳細説明

1. source（データソースの指定）

■ fileInfo：

• specifier：ファイル名（例: TransactionData_20250301.csv）

• contentType：ファイル形式（CSV、TAB など）

• hasMultipleFiles：複数ファイルである場合は、true にします

• standardQuotedStrings：引用符で囲まれた文字列を標準的に扱う場合は true にします

2. target（データのインポート先の指定）

■ type：インポート先のタイプ（DataExtension を入力）
■ key：インポート先のデータエクステンションの外部キー

■ updateType：

• AddAndUpdate：追加と更新

• AddAndDoNotUpdate：追加のみ（※ 更新はされない）

• UpdateButDoNotAdd：更新のみ（※ 追加はされない）

• Overwrite：上書き

3. mapping（フィールドマッピング）

■ allowErrors：true の場合、途中でエラーがあってもプロセスは中断されない
■ fieldMappingType：

• InferFromColumnHeadings：列のヘッダー名を元に自動マッピングする

• MapByOrdinal：列の順序でマッピングする

4. transport（ファイルロケーション）

■ key：設定済みの「ファイルの場所」の外部キー

インポート結果の検証について

インポート結果の検証については、通常のインポートアクティビティではメールアドレスを登録して、その結果を確認していたと思いますが、この API を使用した場合はメールアドレスの登録ができませんので、検証についても API で取得しに行く形になります。

まずインポートのリクエストが完了すると、以下ような結果が返されます。

ここで表示される id は、インポートの「タスク ID」と呼ばれるものです。こちらをメモしておいて下さい。続いて、別のリクエストを立ち上げて、以下を設定します。

--- メソッド 
GET

--- エンドポイント
[REST ベース URL].rest.marketingcloudapis.com/data/v1/async/import/{id}/summary

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

これを実行すると、以下のような情報が返されます。このインポートの場合は、エラー行が 1 行あったことが示されています。

それでは、このエラーの内容を知りたい場合ですが、まず、どの種のエラーであるかを知りたい場合は、以下を設定します。

--- メソッド 
GET

--- エンドポイント
[REST ベース URL].rest.marketingcloudapis.com/data/v1/async/import/{id}/validationsummary

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

これにより、必須項目が存在しないレコードがあることが判明しました。

続いて、具体的にどのレコードが必須項目が存在しないのかを調べる場合は、以下を設定します。

--- メソッド 
GET

--- エンドポイント
[REST ベース URL].rest.marketingcloudapis.com/data/v1/async/import/{id}/validationresult

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

これにより、具体的なレコードと問題が発生している項目名が判明します。

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

このデータエクステンションインポート API は、柔軟性と効率性を提供します。この機能を活用すれば、インポートプロセスを簡素化し、ビジネス要件に合わせたデータ管理が可能になります。

今回は以上です。

次の記事はこちら

前回の記事はこちら

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