Flow Service API を使用して Mailchimp Campaign のデータフローを作成する

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

トピック：

作成対象：

開発者

以下のチュートリアルでは、ソース接続とデータフローを作成し、Flow Service API を使用して Mailchimp Campaign のデータを Platform に取り込む手順を詳しく説明します。

前提条件

OAuth 2 のリフレッシュコードを使用して Adobe Experience Platform に Mailchimp を接続する前に、まず MailChimp. のアクセストークンを取得する必要があります。アクセストークンの取得方法について詳しくは、Mailchimp OAuth 2 ガイドを参照してください。

ベース接続の作成 base-connection

Mailchimp 認証資格情報を取得したら、Mailchimp Campaign データを Platform に取り込むためにデータフローを作成するプロセスを開始できます。データフローを作成する最初の手順は、ベース接続を作成することです。

ベース接続は、ソースと Platform 間の情報（ソースの認証資格情報、現在の接続状態、固有のベース接続 ID など）を保持します。ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。

Mailchimp は、基本認証と OAuth 2 更新コードの両方をサポートしています。いずれかの認証タイプで認証する方法については、次の例を参照してください。

基本認証を使用した Mailchimp ベース接続の作成

基本認証を使用した Mailchimp ベース接続を作成するには、API の /connections エンドポイントにPOSTリクエスト Flow Service 行います。その際、authorizationTestUrl、username、password の資格情報を提供を提供を提供します。

API 形式

POST /connections

リクエスト

次のリクエストは、Mailchimp のベース接続を作成します。

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "Mailchimp base connection with basic authentication",
      "description": "Mailchimp Campaign base connection with basic authentication",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "Basic Authentication",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "username": "{USERNAME}",
              "password": "{PASSWORD}"
          }
      }
  }'

プロパティ

説明

name

ベース接続の名前。ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。

description

（オプション）ベース接続に関する詳細情報を提供するために含めることができるプロパティ。

connectionSpec.id

ソースの接続仕様 ID。この ID は、ソースが登録および承認された後に、Flow Service API から取得することができます。

auth.specName

ソースを Platform に接続するために使用する認証タイプ。

auth.params.authorizationTestUrl

（オプション）認証テスト URL は、ベース接続の作成時に資格情報を検証するために使用されます。指定しない場合、代わりにソース接続の作成時に資格情報が自動的にチェックされます。

auth.params.username

Mailchimp アカウントに対応するユーザー名。これは、基本認証に必要です。

auth.params.password

Mailchimp アカウントに対応するパスワード。これは、基本認証に必要です。

応答

リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。

{
    "id": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

OAuth 2 更新コードコードを使って Mailchimp ベース接続を作成します

OAuth 2 更新コードを使用して Mailchimp ベース接続を作成するには、/connections エンドポイントにPOSTリクエストを送信し、その際、authorizationTestUrl ーザーの資格情報を提供し、accessToken 信します。

API 形式

POST /connections

リクエスト

次のリクエストは、Mailchimp のベース接続を作成します。

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "Mailchimp base connection with OAuth 2 refresh code",
      "description": "Mailchimp Campaign base connection with OAuth 2 refresh code",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "oAuth2RefreshCode",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "accessToken": "{ACCESS_TOKEN}"
          }
      }
  }'

プロパティ

説明

name

ベース接続の名前。ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。

description

（オプション）ベース接続に関する詳細情報を提供するために含めることができるプロパティ。

connectionSpec.id

ソースの接続仕様 ID。この ID は、Flow Service API を使用してソースを登録した後に取得することができます。

auth.specName

Platform へのソースの認証に使用する認証タイプ。

auth.params.authorizationTestUrl

auth.params.accessToken

ソースの認証に使用された、対応するアクセストークン。これは、OAuth ベースの認証に必要です。

応答

{
    "id": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

ソースを参照 explore

前の手順で生成したベース接続 ID を使用することで、GET リクエストを実行してファイルとディレクトリを調べることができます。ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。

パラメーター

説明

{BASE_CONNECTION_ID}

前の手順で生成したベース接続 ID。

{OBJECT_TYPE}

参照するオブジェクトのタイプ。 REST ソースの場合、この値はデフォルトで rest になります。

{OBJECT}

参照するオブジェクト。

{FILE_TYPE}

このパラメーターは、特定のディレクトリを表示する場合にのみ必要です。値は、参照するディレクトリのパスを表します。

{PREVIEW}

接続のコンテンツがプレビューをサポートするかどうかを定義するブール値です。

{SOURCE_PARAMS}

campaign_id を base64 でエンコードした文字列です。

TIP

{SOURCE_PARAMS} に使用できるフォーマットのタイプを取得するには、campaignId の文字列全体を base64 でエンコードする必要があります。例えば、base64 にエンコードされた {"campaignId": "c66a200cda"} は、eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9 と等しくなります。

API 形式

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&objectType={OBJECT_TYPE}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}

リクエスト

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/05c595e5-edc3-45c8-90bb-fcf556b57c4b/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

応答が成功すると、クエリされたファイルの構造を返します。

{
    "data": [
        {
            "emails": [
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "cff65fb4c5f5828666ad846443720efd",
                    "email_address": "kendall2134@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
                        }
                    ]
                },
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "a16b82774b211afaf60902d1afd8abc5",
                    "email_address": "logan9935890967@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
                        }
                    ]
                },
            ]
        }
    ]
}

ソース接続の作成 source-connection

Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。

ソース接続を作成するには、データ形式属性の列挙値も定義する必要があります。

ファイルベースのソースには、次の列挙値を使用します。

データ形式

列挙値

区切り

delimited

JSON

json

PARQUET

parquet

すべてのテーブルベースのソースで、値を tabular に設定します。

API 形式

POST /sourceConnections

リクエスト

次のリクエストは、Mailchimp のソース接続を作成します。

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp source connection to ingest campaign ID",
      "description": "MailChimp Campaign source connection to ingest campaign ID",
      "baseConnectionId": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      },
      "params": {
          "campaignId": "c66a200cda"
      }
  }'

プロパティ

説明

name

ソース接続の名前。ソース接続の情報を検索する際に使用できるので、ソース接続の名前はわかりやすいものにしてください。

description

含めることでソース接続に関する詳細情報を提供できるオプションの値です。

baseConnectionId

Mailchimp のベース接続 ID。この ID は、前の手順で生成されました。

connectionSpec.id

ソースに対応する接続仕様の ID。

data.format

取り込む Mailchimp データの形式。

params.campaignId

Mailchimp キャンペーン ID は特定の Mailchimp キャンペーンを識別し、リストやオーディエンスにメールを送信することを可能にします。

応答

リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。この ID は、後の手順でデータフローを作成する際に必要になります。

{
    "id": "d6557bf1-7347-415f-964c-9316bd4cbf56",
    "etag": "\"e205c206-0000-0200-0000-615b5c070000\""
}

ターゲット XDM スキーマの作成 target-schema

ソースデータを Platform で使用するには、必要に応じてターゲットスキーマを作成してソースデータを構造化する必要があります。次に、ターゲットスキーマを使用して、ソースデータが含まれる Platform データセットを作成します。

Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。

ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。

ターゲットデータセットの作成 target-dataset

Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。

ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。

ターゲット接続の作成 target-connection

ターゲット接続は、取り込まれたデータが取り込まれる宛先への接続を表します。ターゲット接続を作成するには、Data Lake に対応する固定接続仕様 ID を指定する必要があります。この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。

これで、一意の識別子、ターゲットスキーマ、ターゲットデータセット、および Data Lake の接続仕様 ID が用意できました。これらの識別子を使用することで、Flow Service API を使用してターゲット接続を作成し、受信ソースデータを格納するデータセットを指定できます。

API 形式

POST /targetConnections

リクエスト

次のリクエストは、Mailchimp のターゲット接続を作成します。

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp target connection",
      "description": "MailChimp Campaign target connection",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "parquet_xdm",
          "schema": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/570630b91eb9d5cf5db0436756abb110d02912917a67da2d",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "6155e3a9bd13651949515f14"
      }
  }'

プロパティ

説明

name

ターゲット接続の名前。ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。

description

ターゲット接続に関する詳細を提供するために含めることができるオプションの値です。

connectionSpec.id

Data Lakeに対応する接続仕様 ID。この修正済み ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。

data.format

Platform に取り込む Mailchimp データの形式。

params.dataSetId

前の手順で取得したターゲットデータセット ID。

応答

リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。この ID は、後の手順で必要になります。

{
    "id": "9463fe9c-027d-4347-a423-894fcd105647",
    "etag": "\"b902e822-0000-0200-0000-615b5c370000\""
}

IMPORTANT

現在、Mailchimp Campaign では Data 準備機能はサポートされていません。

フローの作成 flow

Mailchimp データを Platform に取り込むための最後の手順は、データフローを作成することです。現時点で、次の必要な値の準備ができています。

ソース接続 ID
ターゲット接続 ID

データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。ペイロードに前述の値を提供しながら POST リクエストを実行することで、データフローを作成することができます。

取り込みをスケジュールするには、まず開始時刻の値をエポック時間（秒）に設定する必要があります。次に、頻度の値を次の 5 つのいずれかに設定する必要があります。 once、minute、hour、day、week。インターバルの値は、2 つの連続した取り込みの間隔を指定します。1 回のみの取り込み（once）を作成する際は、インターバルを設定する必要はありません。その他のすべての頻度では、インターバルの値を 15 以上に設定する必要があります。

API 形式

POST /flows

リクエスト

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp Campaign dataflow",
      "description": "MailChimp Campaign dataflow",
      "flowSpec": {
          "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "d6557bf1-7347-415f-964c-9316bd4cbf56"
      ],
      "targetConnectionIds": [
          "9463fe9c-027d-4347-a423-894fcd105647"
      ],
      "scheduleParams": {
          "startTime": "1632809759",
          "frequency": "minute",
          "interval": 15
      }
  }'

プロパティ

説明

name

データフローの名前。データフローの情報を検索する際に使用できるので、データフローはわかりやすい名前にしてください。

description

（オプション）データフローの詳細を提供するために含めることができるプロパティ。

flowSpec.id

データフローの作成に必要なフロー仕様 ID。この修正済み ID は 6499120c-0b15-42dc-936e-847ea3c24d72 です。

flowSpec.version

フロー仕様 ID の対応するバージョン。この値のデフォルトは 1.0 です。

sourceConnectionIds

以前の手順で生成されたソース接続 ID。

targetConnectionIds

以前の手順で生成されたターゲット接続 IDです。

scheduleParams.startTime

データの最初の取り込みが開始される、指定された開始時間。

scheduleParams.frequency

データフローがデータを収集する頻度。指定できる値は、once、minute、hour、day、week です。

scheduleParams.interval

インターバルは 2 つの連続したフロー実行の間隔を指定します。インターバルの値はゼロ以外の整数にしてください。頻度が once に設定されている場合、間隔は必須ではありません。また、頻度は他の頻度の値に対して、15 よりも大きいか、等しい必要があります。

応答

正常な応答は、新しく作成したデータフローの ID（id）を返します。この ID を使用して、データフローを監視、更新または削除できます。

{
    "id": "be2d5249-eeaf-4a74-bdbd-b7bf62f7b2da",
    "etag": "\"7e010621-0000-0200-0000-615b5c9b0000\""
}

付録

次の節では、データフローの監視、更新、削除を行う手順について説明します。

データフローの監視

データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。完全な API の例については、API を使用したソースデータフローのモニタリングに関するガイドを参照してください。

データフローの更新

データフローの ID を指定しながら API の /flows エンドポイントにPATCHリクエストを実行することで、名前や説明、実行スケジュールや関連するマッピングセットなど、データフローの詳細 Flow Service 更新できます。データフローをリクエストする場合は、PATCHの一意の etag を If-Match ヘッダーで指定する必要があります。完全な API の例については、API を使用したソースデータフローの更新に関するガイドを参照してください。

アカウントを更新

ベースPATCHID をクエリパラメーターとして指定して Flow Service API に接続リクエストを実行することで、ソースアカウントの名前、説明、資格情報を更新します。 PATCHリクエストを行う場合は、ソースアカウントの一意の etag を If-Match ヘッダーで指定する必要があります。完全な API の例については、API を使用したソースアカウントの更新に関するガイドを参照してください。

データフローの削除

クエリパラメーターの一部として削除するデータフローの ID を指定したうえで Flow Service API に対してDELETEリクエストを実行することで、データフローを削除します。完全な API の例については、API を使用したデータフローの削除に関するガイドを参照してください。

アカウントを削除

削除するアカウントのベースDELETEID を指定したうえで、Flow Service API に接続リクエストを実行してアカウントを削除します。完全な API の例については、API を使用したソースアカウントの削除に関するガイドを参照してください。

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089