# Adobe Marketo Engage への接続 Adobe Marketo Engage は、マーケティング担当者が見込み客や顧客向けにパーソナライズされたマルチチャネルプログラムやキャンペーンを管理できるようにするマーケティング自動化プラットフォームです。 **Topics** + [Adobe Marketo Engage の AWS Glue サポート](adobe-marketo-engage-support.md) + [接続を作成および使用するための API オペレーションを含むポリシー](adobe-marketo-engage-configuring-iam-permissions.md) + [Adobe Marketo Engage の設定](adobe-marketo-engage-configuring.md) + [Adobe Marketo Engage 接続の設定](adobe-marketo-engage-configuring-connections.md) + [Adobe Marketo Engage エンティティからの読み取り](adobe-marketo-engage-reading-from-entities.md) + [Adobe Marketo Engage エンティティへの書き込み](adobe-marketo-engage-writing-to-entities.md) + [Adobe Marketo Engage 接続オプション](adobe-marketo-engage-connection-options.md) + [Adobe Marketo Engage コネクタの制限事項と注意事項](adobe-marketo-engage-connector-limitations.md) # Adobe Marketo Engage の AWS Glue サポート AWS Glue は、次のように Adobe Marketo Engage をサポートします。 **ソースとしてサポートされていますか?** はい。AWS Glue ETL ジョブを使用して、Adobe Marketo Engage からデータをクエリできます。 **ターゲットとしてサポートされているかどうか** はい。AWS Glue ETL ジョブを使用して、Adobe Marketo にデータを書き込むことができます。 **サポートされている Adobe Marketo Engage API バージョン** 次の Adobe Marketo Engage API バージョンがサポートされています。 + v1 バージョン固有のエンティティサポートについては、「ソースに対応するエンティティ」を参照してください。 # 接続を作成および使用するための API オペレーションを含むポリシー 次のサンプル ポリシーで、接続の作成と使用に必要な AWS IAM 権限について説明します。新しいロールを作成する場合は、以下を含むポリシーを作成します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ 上記の方法を使用しない場合は、代わりに次のマネージド IAM ポリシーを使用します: + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – さまざまな AWS Glue プロセスを実行するために必要なリソースへのアクセス権をユーザーに代わって付与します。これらのリソースには AWS Glue 、Amazon S3、IAM、CloudWatch Logs、および Amazon EC2 が含まれます。このポリシーで指定されたリソースの命名規則に従った場合、AWS Glue プロセスは必要なアクセス権限を使用できます。このポリシーは、通常、クローラ、ジョブ、開発エンドポイントを定義するときに指定されたロールにアタッチされます。 + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) — ポリシーがアタッチされているアイデンティティが AWS マネージメントコンソールを使用するときは、AWS Glue リソースへのフルアクセスを許可します。このポリシーで指定されたリソースの命名規則に従った場合、ユーザーは完全なコンソール機能を使用できます。このポリシーは、通常 AWS Glue コンソールのユーザーにアタッチされています。 # Adobe Marketo Engage の設定 AWS Glue を使用して Adobe Marketo Engage からデータを転送できるようにするには、次の要件を満たす必要があります。 ## 最小要件 以下に、最小要件を示します。 + クライアント認証情報を持つ Adobe Marketo Engage アカウントがあること。 + Adobe Marketo Engage アカウントに、有効なライセンスで API アクセスがあること。 これらの要件を満たしている場合、AWS Glue を Adobe Marketo Engage アカウントに接続する準備ができています。一般的な接続の場合、Adobe Market Engage で他に何もする必要はありません。 ## OAuth 2.0 認証情報の取得 インスタンスに対して認証された呼び出しを行うための API 認証情報を取得するには、「[Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api)」を参照してください # Adobe Marketo Engage 接続の設定 Adobe Marketo Engage は、OAuth2 の CLIENT CREDENTIALS グラントタイプをサポートしています。 + このグラントタイプは、クライアントがユーザーのコンテキスト外でアクセストークンを取得するために使用するため、2-legged の OAuth 2.0 と見なされます。AWS Glue は、クライアント ID とクライアントシークレットを使用して、定義したカスタムサービスによって提供される Adobe Marketo Engage API を認証できます。 + 各カスタムサービスは、特定のアクションを実行することをサービスに許可する一連のロールとアクセス許可を持つ API 専用ユーザーによって所有されます。アクセストークンは 1 つのカスタムサービスに関連付けられています。 + このグラントタイプは、有効期間が短いアクセストークンになり、ID エンドポイントを呼び出すことで更新される場合があります。 + クライアント認証情報を使用した OAuth 2.0 の Adobe Marketo Engage の公開ドキュメントについては、「Adobe Marketo Engage デベロッパーガイド」の「[認証](https://developers.adobe-marketo-engage.com/rest-api/authentication/)」を参照してください。 Adobe Marketo Engage 接続を設定するには: 1. AWS Secrets Manager で、次の詳細を含むシークレットを作成します。 1. カスタマーマネージド接続アプリケーションの場合、シークレットには、`USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` を使用して接続されたアプリケーションのコンシューマーシークレットをキーとして含める必要があります。 1. 注: AWS Glue で接続ごとにシークレットを作成する必要があります。 1. AWS Glue Glue Studio で、以下の手順に従って **[データ接続]** の下に接続を作成します。 1. **[接続タイプ]** を選択する際に、Adobe Marketo Engage を選択します。 1. 接続先の Adobe Marketo Engage インスタンスの `INSTANCE_URL` を指定します。 1. AWS Glue が次のアクションを引き受けて、その権限を持つことができる AWS IAM ロールを選択します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. AWS Glue でこの接続に使用する `secretName` を選択して、トークンを配置します。 1. ネットワークを使用する場合は、ネットワークオプションを選択します。 1. AWS Glue ジョブに関連付けられている IAM ロールに `secretName` を読み取るアクセス許可を付与します。 # Adobe Marketo Engage エンティティからの読み取り **前提条件** 読み取り元の Adobe Marketo Engage オブジェクト。leads、activities、customobjects などのオブジェクト名が必要になります。次の表は、サポートされているエンティティを示しています。 **ソース (同期) でサポートされているエンティティ**: | エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティション分割をサポートする | | --- | --- | --- | --- | --- | --- | | leads | あり | あり | なし | あり | なし | | アクティビティ | あり | あり | なし | あり | なし | | customobjects | あり | あり | なし | あり | なし | **ソース (非同期) でサポートされているエンティティ**: | エンティティ | フィルタリング可能 | 制限をサポートする | Order By をサポートする | Select \$1 をサポートする | パーティション分割をサポートする | | --- | --- | --- | --- | --- | --- | | leads | あり | なし | なし | あり | あり | | アクティビティ | あり | なし | なし | あり | なし | | customobjects | あり | なし | なし | あり | あり | **例**: ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v2", "INSTANCE_URL": "https://539-t**-6**.mktorest.com" } ``` **Adobe Marketo Engage エンティティとフィールドの詳細**: **静的メタデータを持つエンティティ**: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) **動的メタデータを持つエンティティ**: 以下のエンティティの場合、Adobe Marketo Engage はメタデータを動的にフェッチするエンドポイントを備えているため、演算子のサポートは各エンティティのデータ型レベルでキャプチャされます。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) ## パーティショニングクエリ Spark で同時実行を使用する場合は、追加の Spark オプション `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND`、および `NUM_PARTITIONS` を指定できます。これらのパラメータを使用すると、元のクエリは Spark タスクで同時に実行できるサブクエリの `NUM_PARTITIONS` の数に分割されます。 + `PARTITION_FIELD`: クエリのパーティション化に使用するフィールドの名前。 + `LOWER_BOUND`: 選択したパーティションフィールドの**包括的な**下限値。 DateTime フィールドでは、ISO 形式の値を受け入れます。 有効な値の例: ``` "2024-07-01T00:00:00.000Z" ``` + `UPPER_BOUND`: 選択したパーティションフィールドの**排他的**上限値。 + `NUM_PARTITIONS`: パーティション数。 次の表に、エンティティパーティション分割フィールドのサポートの詳細を示します: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) 例: ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2024-07-01T00:00:00.000Z" "UPPER_BOUND": "2024-07-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # Adobe Marketo Engage エンティティへの書き込み **前提条件** + 書き込み先の Adobe Marketo オブジェクト。`leads` または `customobjects` などのオブジェクト名が必要です。 + Adobe Marketo コネクタは、次の 3 つの書き込みオペレーションをサポートしています。 + INSERT + UPSERT + UPDATE + `UPSERT` および `UPDATE` 書き込みオペレーションでは、レコードの ID フィールドを指定する `ID_FIELD_NAMES` オプションを指定する必要があります。`leads` エンティティを使用する場合は、`email` を `ID_FIELD_NAMES` として `UPSERT` オペレーションに、`id` を `UPDATE` オペレーションに使用します。`customobjects` エンティティの場合は、`UPDATE` オペレーションと `UPSERT` オペレーションの両方に `marketoGUID` を `ID_FIELD_NAMES` として使用します。 **Destination (Synchronous) でサポートされているエンティティ** | エンティティ名 | Destination Connector としてサポートされます | 挿入可能 | 更新可能 | アップサート可能 | | --- | --- | --- | --- | --- | | leads | はい | はい (バルク) | はい (バルク) | はい (バルク) | | customobjects | はい | はい (バルク) | はい (バルク) | はい (バルク) | **例**: **INSERT オペレーション:** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "INSERT" } ``` **Update オペレーション:** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "UPDATE", "ID_FIELD_NAMES": "id" } ``` **注記** `leads` および `customobjects` エンティティの場合、Adobe Marketo はメタデータを動的に取得するエンドポイントを提供するため、書き込み可能なフィールドは Marketo API レスポンスから識別されます。 # Adobe Marketo Engage 接続オプション Adobe Marketo Engage の接続オプションは次のとおりです。 + `ENTITY_NAME`(文字列) – (必須) 読み取りに使用されます。Adobe Marketo Engage のオブジェクトの名前。 + `API_VERSION`(文字列) – (必須) 読み取りに使用されます。使用する Adobe Marketo Engage Rest API バージョン。例: v1。 + `SELECTED_FIELDS`(List) – Default: empty(SELECT \$1). 読み込みに使用されます。オブジェクトに選択する列です。 + `FILTER_PREDICATE`(文字列) – デフォルト: 空 読み込みに使用されます。Spark SQL 形式である必要があります。 + `QUERY`(文字列) - デフォルト: 空 読み込みに使用されます。完全な Spark SQL クエリです。 + `PARTITION_FIELD`(文字列) - 読み取りに使用されます。クエリをパーティション化するために使用するフィールドです。 + `LOWER_BOUND`(文字列) - 読み取りに使用されます。選択したパーティションフィールドの包括的な下限値。 + `UPPER_BOUND` (文字列) - 読み取りに使用されます。選択したパーティションフィールドの排他的上限値。 + `NUM_PARTITIONS`(整数) – デフォルト: 1。読み込みに使用されます。読み取り用のパーティションの数です。 + `TRANSFER_MODE` (文字列) – デフォルト: SYNC。非同期読み取りに使用されます。 + `WRITE_OPERATION`(文字列) - デフォルト: INSERT。書き込みに使用されます。値は INSERT、UPDATE、UPSERT である必要があります。 + `ID_FIELD_NAMES`(文字列) - デフォルト: null。UPDATE および UPSERT に必要です。 # Adobe Marketo Engage コネクタの制限事項と注意事項 Adobe Marketo Engage コネクタの制限事項または注意事項は次のとおりです。 + 'sinceDatetime' と 'activityTypeId' は、同期アクティビティエンティティの必須フィルターパラメータです。 + サブスクリプションには、1 日あたり 50,000 件の API コールが割り当てられます (中部標準時で毎日午前 12:00 にリセットされます)。Adobe Marketo Engage サブスクリプションの一部として、1 日あたりの容量を追加購入できます。リファレンスについては、「[Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api)」を参照してください。 + 日付範囲フィルター (`createdAt` または `updatedAt`) の最大期間は 31 日間です。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + サブスクリプションには、いつでもキューに最大 10 個の一括抽出ジョブが割り当てられます。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + デフォルトでは、抽出ジョブは 1 日あたり 500 MB に制限されています (中部標準時で毎日午前 12:00 にリセットされます)。Adobe Marketo Engage サブスクリプションの一部として、1 日あたりの容量を追加購入できます。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + 同時エクスポートジョブの最大数は 2 です。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + キューに入れられたエクスポートジョブ (現在エクスポート中のジョブを含む) の最大数は 10 です。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + 一括ジョブから抽出できる最大許容ファイルサイズは 1 GB です。 + 非同期ジョブが作成されると、ファイル保持期間は有効期限の 7 日前になります。リファレンスについては、「[一括抽出 - Marketo 開発者](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)」を参照してください。 + `createdAt` または `updatedAt` は、非同期リードエンティティの必須フィルターパラメータです。 + `createdAt` は、非同期アクティビティエンティティの必須フィルターパラメータです。 + `updatedAt` は、非同期カスタムオブジェクトエンティティの必須フィルターパラメータです。 + AWS Glue SaaS コネクタを使用する場合、ユーザーは、部分的な障害が発生した場合に、送信先 SaaS プラットフォームへの書き込みオペレーション中に失敗した特定のレコードを特定できません。 + Sync 書き込みオペレーションを使用する場合、入力ファイル内の null 値を持つフィールドは自動的に削除され、SaaS プラットフォームに送信されません。 + Sync 書き込みでは、バッチで最大 300 個のレコードを作成または更新できます。 詳細については、「[Adobe Marketo Engage 統合ベストプラクティス](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/marketo-integration-best-practices)」および「[一括抽出](https://https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-activity-extract)」を参照してください。