Data Ingestion API

Data Ingestion APIは、大量、低遅延、高可用性のサービスです。 最小限の遅延で膨大な個人および人関連データを取り込むことができます。

データ収集リクエストは非同期で実行されます。 リクエストのステータスを取得するには、Marketo Observability Data Streamからイベントを購読します。

APIには、次の5つのオブジェクトタイプのインターフェイスが用意されています。

Data Ingestion API ドキュメント ​を参照してください。

認証

Data Ingestion APIは、Marketo REST APIと同じOAuth 2.0認証方法を使用してアクセストークンを生成します。 X-Mkto-User-Token HTTP ヘッダーにアクセストークンを渡します。 クエリパラメーターとして渡すことはできません。

次の例では、ヘッダーにアクセストークンを渡します。

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

権限

Data Ingestionは、Marketo REST API権限モデルを使用します。追加の権限は必要ありません。 次の表に示すように、各エンドポイントには特定の既存の権限が必要です。

サポートされているオブジェクトタイプ

ヘッダー

データ取り込みは、次のカスタム HTTP ヘッダーをサポートしています。

リクエスト

応答

リクエスト

HTTP POST メソッドを使用してサーバーにデータを送信します。

リクエスト本文にapplication/jsonとしてデータを含めます。

ドメイン mkto-ingestion-api.adobe.ioを使用します。

パスは/subscriptions/MunchkinIdで始まり、MunchkinIdはMarketo インスタンスに固有です。 Munchkin IDは、Marketo Engage UIの​管理者/マイアカウント/サポート情報​で確認できます。 パスの残りの部分でリソースを指定します。

ユーザの URL の例：

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

カスタムオブジェクトの URL の例：

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

企業のURLの例：

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/companies

プログラムメンバーのURLの例：

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/programmembers

リストのURLの例：

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/lists

応答

すべての応答は、X-Request-Id ヘッダー内の一意のリクエスト IDを返します。

ヘッダー経由のリクエスト ID の例：

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

成功

呼び出しが成功すると、ステータス 202が返され、応答本文は返されません。

成功応答の例：

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

エラー

呼び出しが失敗すると、202以外のステータスと、エラーの詳細が記載された応答本文が返されます。 application/json応答本文には、error_codeおよびmessage人のメンバーを持つ1つのオブジェクトが含まれています。

次のエラーコードは、Adobe Developer Gatewayから再利用されます。

Data Ingestion API固有のエラーコードには、Adobe Developer Gatewayから返される3桁のステータス、ゼロの「0」、および3桁の追加の数字の3つのセグメントが含まれています。

再試行

サービスが一時的なエラーを検出すると、操作を再試行します。 再試行は、主に依存サービスがタイムアウトするか、一時的に利用できない場合に発生します。

サービスは、次の再試行間隔を使用します。

エンドポイント

取り込みエンドポイントは、個人、カスタムオブジェクト、会社、プログラムメンバーおよびリストに対して使用できます。 各エンドポイントセクションでは、リクエストを定義し、例を示します。

ユーザ

このエンドポイントを使用して、個人レコードをアップサートします。

ヘッダー

リクエスト本文

必須の権限は Read-Write Lead です。

ユーザの例

リクエスト

POST /subscriptions/{munchkinId}/persons

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

カスタムオブジェクト

このエンドポイントを使用して、カスタムオブジェクトレコードをアップサートします。

ヘッダー

リクエスト本文

必須の権限は Read-Write Custom Object です。

リクエストでユーザへのリンクフィールドが指定され、そのユーザが存在しない場合は、複数回の再試行が行われます。 再試行ウィンドウ（65 分）内にそのユーザが追加された場合、更新は成功します。 例えば、リンクフィールドがユーザの email であり、ユーザが存在しない場合は再試行が行われます。

カスタムオブジェクトの例

リクエスト

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

会社

このエンドポイントを使用して、会社レコードを同期します。 外部の会社IDまたはMarketoの内部IDによる重複排除を使用して、作成、更新、アップサート操作をサポートします。

ヘッダー

リクエスト本文

input配列内の各会社オブジェクトは、次のフィールドをサポートしています。

必須の権限は Read-Write Company です。

企業の例

リクエスト

POST /subscriptions/{munchkinId}/companies

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

企業のIDによる更新の例

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

会社の検証ルール

プログラムメンバー（同期）

プログラムメンバーのステータスを同期したり、リードをプログラムに追加したり、プログラムステータスを更新したりするために使用されるエンドポイント。

ヘッダー

リクエスト本文

programs配列内の各オブジェクトには、次のものが含まれます。

members配列内の各オブジェクトには、次のものが含まれます。

必須の権限は Read-Write Lead です。

プログラムメンバーの同期例

リクエスト

POST /subscriptions/{munchkinId}/programmembers

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

プログラムメンバーの同期検証ルール

プログラムメンバー（削除）

プログラムからリードを削除するために使用されるエンドポイント。 これにより、リードのメンバーシップ ステータスが"Not in Program"に設定され、そのプログラムからメンバーが削除されます。

ヘッダー

リクエスト本文

programs配列内の各オブジェクトには、次のものが含まれます。

members配列内の各オブジェクトには、次のものが含まれます。

必須の権限は Read-Write Lead です。

プログラムメンバーの削除例

リクエスト

POST /subscriptions/{munchkinId}/programmembers/delete

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

プログラムメンバーが検証ルールを削除

リスト （リストに追加）

静的リストにリードを追加するために使用されるエンドポイント。 リードは、Marketoのリード IDで識別されます。

ヘッダー

リクエスト本文

入力配列内の各オブジェクトには、次のものが含まれます。

必須の権限は Read-Write Lead です。

リストに追加する例

リクエスト

POST /subscriptions/{munchkinId}/lists

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      },
      {
         "leadId": 10003
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

リストに追加するリストの検証ルール

リスト （リストから削除）

静的リストからリードを削除するために使用されるエンドポイント。 リードは、Marketoのリード IDで識別されます。

ヘッダー

リクエスト本文

入力配列内の各オブジェクトには、次のものが含まれます。

必須の権限は Read-Write Lead です。

リストから削除する例

リクエスト

POST /subscriptions/{munchkinId}/lists/remove

ヘッダー

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

本文

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      }
   ]
}

応答

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

リストの検証ルールからリストを削除

制限

Data Ingestion APIには、次のガードレールがあります。

これらの制限は、個人、カスタムオブジェクト、会社、プログラムメンバー、およびリストに対して一様に適用されます。 プログラムメンバーの場合、「リクエストごとのオブジェクト」は、1回のリクエスト内のすべてのプログラムにわたるリード参照の合計数です。 リストの場合、「リクエストごとのオブジェクト」は、入力配列内のリード参照の数です。

Data Ingestion API と REST API

Data Ingestion APIは、次の点で他のMarketo REST APIとは異なります。