見出し画像
Photo by akisuke0925

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

Nobuyuki Watanabe

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

主な特徴とメリット

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

  • Amazon S3

  • Google Cloud Storage

  • Microsoft Azure Blob Storage

  • 外部の SFTP

注意：Salesforce Marketing Cloud 専用 SFTP の使用について
私のテストの結果、SFMC 専用の SFTP を使用した場合、一度のみインポート可能であり、その後、インポートに使用したファイルが自動的に削除されることが確認されました。そのため、SFMC 専用 SFTP での利用は推奨されません。ただし、ファイルの削除が問題にならない場合は、例外的に利用を検討できます。外部 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 を使用します。過去の連載「Marketing Cloud REST API 超入門」の Part.1 と Part.2 で紹介した以下の 2 つが必要です。

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

今回、以下のスコープがセットアップで選択されている必要があります。
■ AUTOMATION - Automation - Read
■ AUTOMATION - Automation - Execute

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"
    }
}

以下を参考に、書き換えを行ってください。

■ source・・・元ファイルの情報です。CSV ファイル名などを入力します。
■ target・・・格納先 DE の情報です。key にデータエクステンションの外部キーを入力して、updateType にファイルの更新方法を入力します。
■ mapping・・・fieldMappingType にマッピング方法を入力します。
■ transport・・・設定済みの「ファイルの場所」の外部キーです。

各項目の詳細説明

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 のトップページはこちら