Data Ingestion API

Data Ingestion API は、大量のユーザおよびユーザ関連データの取り込みを効率的で最小限の遅延で処理するように設計された、大容量、低遅延、高可用性のサービスです。

データは、非同期で実行されるリクエストを送信することで取り込まれます。 リクエストのステータスは、Marketo Observability Data Streamからイベントを購読することで取得できます。

インターフェイスは、人物、カスタムオブジェクト、会社、プログラムメンバーの4つのオブジェクトタイプに対して提供されます。 レコード操作は、「挿入または更新」のみです。ただし、削除もサポートするプログラムメンバーは除きます。

認証

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

ヘッダー経由のアクセストークンの例：

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

権限

データ取り込みでは、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

応答

すべての応答は、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 を持つ単一のオブジェクトが含まれます。

Adobe Developer Gateway から再利用されたエラーコードを以下に示します。

Data Ingestion API に一意の、3 つのセグメントで構成されるエラーコードを以下に示します。 最初の 3 桁は、ステータス（Adobe Developer Gateway によって返される）で、その後にゼロ「0」が続き、その後に 3 桁の数字が続きます。

再試行

一時的なエラーが検出されると、サービスは操作を 3 回再試行します。 最初の再試行は 5 分間の待機期間後に行われ、2 回目はさらに 30 分後に行われ、最後に 3 回目はさらに 30 分後に行われます。 再試行は様々な理由で発生しますが、主に依存するサービスがタイムアウトになった場合や、一時的に使用できない場合に発生します。

エンドポイント

取り込みエンドポイントは、個人、カスタムオブジェクト、会社、プログラムメンバーに対して使用できます。

ユーザ

ユーザレコードのアップサートに使用されるエンドポイント。

ヘッダー

リクエスト本文

必須の権限は 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 分）内にそのユーザが追加された場合、更新は成功します。 例えば、リンクフィールドがユーザのメールであり、ユーザが存在しない場合は再試行が行われます。

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

リクエスト

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

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

制限

更新されたガードレールのリストを次に示します。

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

Data Ingestion API と REST API

Data Ingestion API と他の Marketo REST API の違いのリストを以下に示します。