リードデータベース

Marketo Lead Database APIは、Marketoと個人および人物関連のデータを交換します。 このデータには、アクティビティ、機会、企業が含まれます。

オブジェクト

リードデータベースには、次のオブジェクトが含まれます。

  • リード
  • 会社/アカウント
  • 重点顧客
  • 商談
  • 商談ロール
  • セールス担当者
  • カスタムオブジェクト
  • アクティビティ
  • リストとプログラムメンバーシップ

ほとんどのリードデータベースオブジェクトは、作成、読み取り、更新および削除メソッドをサポートしています。 Describe メソッドには、各オブジェクトタイプで使用可能なフィールドが用意されています。 リード以外のオブジェクトの場合は、重複排除に使用されるフィールドと、レコードの取得時に検索可能なフィールドも識別します。

リードオブジェクトは、Marketo アプリケーションで最も多様な用途をリードに持つため、最も幅広い機能セットをサポートします。

API

リードデータベース API エンドポイント、パラメーター、モデリング情報の完全なリストについては、​ リードデータベース API エンドポイント リファレンス ​を参照してください。

インスタンスにネイティブのMicrosoft DynamicsまたはSalesforce.com CRM統合がある場合、会社、商談、商談ロール、および営業担当者のAPIは無効になります。 CRMはこれらのレコードを管理するため、Marketo APIを通じてレコードにアクセスしたり更新したりすることはできません。

  • 最大バッチサイズ(標準):300 個のレコード
  • 最大バッチサイズ(一括):10 MB のファイル
  • デフォルトのバッチサイズ:300 個のレコード
  • Content-type ヘッダー(標準):application/json
  • Content-type ヘッダー(一括):multipart/form-data

説明

Describe APIは、リード、企業、商談、役割、セールス担当者、カスタムオブジェクトに対して使用できます。 これを使用すると、更新やクエリに使用できるオブジェクトメタデータとフィールドを取得できます。

リードを記述を除き、各Describe エンドポイントは次を返します。

  • dedupeFields:重複排除に使用できるキー。
  • searchableFields: クエリに使用できるキー。
GET /rest/v1/opportunities/roles/describe.json
{
   "requestId":"185d6#14b51985ff0",
   "success":true,
   "result":[
      {
         "name":"opportunityRole",
         "displayName":"Opportunity Role",
         "createdAt":"2015-02-03T22:36:23Z",
         "updatedAt":"2015-02-03T22:36:24Z",
         "idField":"marketoGUID",
         "dedupeFields":[
            "externalOpportunityId",
            "leadId",
            "role"
         ],
         "searchableFields":[
            [
               "externalOpportunityId",
               "leadId",
               "role"
            ],
            [
               "marketoGUID"
            ],
            [
               "leadId"
            ],
            [
               "externalOpportunityId"
            ]
         ],
         "fields":[
            {
               "name":"marketoGUID",
               "displayName":"Marketo GUID",
               "dataType":"string",
               "length":36,
               "updateable":false
            },
            {
               "name":"externalOpportunityId",
               "displayName":"External Opportunity Id",
               "dataType":"string",
               "length":50,
               "updateable":false
            },
            {
               "name":"leadId",
               "displayName":"Lead Id",
               "dataType":"integer",
               "updateable":false
            },
            {
               "name":"role",
               "displayName":"Role",
               "dataType":"string",
               "length":50,
               "updateable":false
            },
            {
               "name":"isPrimary",
               "displayName":"Is Primary",
               "dataType":"boolean",
               "updateable":true
            },
            {
               "name":"externalCreatedDate",
               "displayName":"External Created Date",
               "dataType":"datetime",
               "updateable":true
            }
         ]
      }
   ]
}

この例では、dedupeFieldsは複合キーです。 今後の作成と更新にdedupeFields モードを使用する場合は、各役割にexternalOpportunityId、leadIdおよびroleを含めてください。

searchableFields配列には、役割レコードのクエリに使用できるフィールドが一覧表示されます。 このリストには、externalOpportunityId、leadId、roleの複合キーが含まれています。

fields応答パラメーターは、各フィールドに次の情報を提供します。

  • 名前:
  • Marketo UIに表示されているdisplayName。
  • データタイプ:
  • 作成後にフィールドを更新できるかどうか。
  • フィールドの長さ(該当する場合)。

クエリ

リードデータベースオブジェクトは、1つのフィールドを参照する単純なキーの基本的なクエリパターンを共有します。

GET /rest/v1/{type}.json?filterType={field to query}&filterValues={comma-separated list of possible values}

リードを除くすべてのオブジェクトに対して、対応する記述応答でsearchableFieldsから{field to query}を選択します。 最大300個の値のコンマ区切りリストを指定します。

また、次のオプションのクエリパラメーターも含めることができます。

  • batchSize:返す結果の数を指定する整数。 デフォルト値と最大値は300です。
  • nextPageToken: ページングの前の呼び出しから返されたトークン。 詳しくは、​ トークンのページング ​を参照してください。
  • fields:各レコードに対して返されるフィールド名のコンマ区切りリスト。 有効なフィールドについては、対応する説明を参照してください。 返されないフィールドをリクエストした場合、その値はnullであることが暗黙的に示されます。
  • _method: POST HTTP メソッドを使用してクエリを送信します。 使用方法については、_method=GET セクションを参照してください。

次の例では、商談に対してクエリを実行します。

GET /rest/v1/opportunities.json?filterType=idField&filterValues=dff23271-f996-47d7-984f-f2676861b5fa&dff23271-f996-47d7-984f-f2676861b5fc,dff23271-f996-47d7-984f-f2676861b5fb
{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fa ",
         "externalOpportunityId":"19UYA31581L000000",
         "name":"Chairs",
         "description":"Chairs",
         "amount":"1604.47",
         "source":"Inbound Sales Call/Email"
      },
      {
         "seq":1,
         "marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fc ",
         "externalOpportunityId":"29UYA31581L000000",
         "name":"Big Dog Day Care-Phase12",
         "description":"Big Dog Day Care-Phase12",
         "amount":"1604.47",
         "source":"Email"
      }
   ]
}

この呼び出しのfilterTypeは、「marketoGUID」ではなく「idField」です。 「idField」と「dedupeFields」の両方は、対応するフィールドにエイリアスを使用できる特殊なケースです。 呼び出しは「marketoGUID」を明示的に設定していませんが、ルックアップフィールドは残ります。

オブジェクトの説明でidFieldとdedupeFieldsによって識別されたフィールドまたはフィールドセットは、クエリに対して常に有効なfilterTypesです。 この呼び出しは、filterValuesのGUIDに一致するレコードを返します。 一致するレコードがない場合、応答は成功を示し、空の結果配列を返します。

一致するレコードセットが300または指定されたbatchSizeのいずれか小さい方を超える場合、応答には値がtrueのmoreResultとnextPageTokenが含まれます。 その後の呼び出しにトークンを含めて、より多くのレコードを取得します。 詳しくは、​ トークンのページング ​を参照してください。

長い URI

URIは、GUIDでクエリする場合など、REST サービスの8 KB制限を超える可能性があります。 この場合は、GETの代わりにHTTP POST メソッドを使用し、_method=GET クエリパラメーターを追加します。

POST本文の残りのクエリパラメーターを「application/x-www-form-urlencoded」文字列として渡します。 関連するコンテンツタイプヘッダーも渡します。

POST /rest/v1/opportunities.json?_method=GET
Content-Type: application/x-www-form-urlencoded
filterType=idField&filterValues=dff23271-f996-47d7-984f-f2676861b5fa&dff23271-f996-47d7-984f-f2676861b5fc,dff23271-f996-47d7-984f-f2676861b5fb,544fb7f5-2ddf-4fca-ae32-7e6ef1415e9f,f1ba41a2-69d1-4a35-9807-0e159d66f2c9,f7521272-3331-4a89-a768-222baff2f894

複合キーをクエリする場合は、_method=GET パラメーターも必要です。

複合キー

複合キーをクエリするには、JSON本文を使用してPOST リクエストを送信します。 このパターンは、filterTypeが複数のフィールドを持つdedupeFields オプションである場合にのみ使用してください。

複合キーは現在、商談ロールと一部のカスタムオブジェクトでのみ使用されています。 次の例では、dedupeFieldsの複合キーを使用して商談ロールをクエリします。

POST /rest/v1/opportunities/roles.json?_method=GET
{
   "filterType":"dedupeFields",
   "fields":[
      "marketoGuid",
      "externalOpportunityId",
      "leadId",
      "role"
   ],
   "input":[
      {
        "externalOpportunityId":"Opportunity1",
        "leadId": 1,
        "role": "Captain"
      },
      {
        "externalOpportunityId":"Opportunity2",
        "leadId": 1872,
        "role": "Commander"
      },
      {
        "externalOpportunityId":"Opportunity3",
        "leadId": 273891,
        "role": "Lieutenant Commander"
      }
   ]
}

JSON オブジェクトは、filterValuesを除く単純キークエリに使用されるすべてのクエリパラメーターを受け入れます。 filterValuesの代わりに、JSON オブジェクトの「入力」配列を指定します。 各オブジェクトには、複合キーのすべてのフィールドを含める必要があります。 この例では、フィールドはexternalOpportunityId、leadIdおよびroleです。

リクエストは指定された入力に対してrolesをクエリし、一致する結果を返します。 応答にmoreResult=trueとnextPageTokenが含まれる場合は、すべての元の入力とnextPageTokenを次のリクエストに含めます。

作成と更新

JSON本文を使用してPOST リクエストを送信することで、リードデータベースレコードを作成および更新します。 商談、役割、カスタムオブジェクト、企業、営業担当者は、同じインターフェイスを使用しています。 リードは別のインターフェイスを使用します。詳しくは、リードのドキュメントを参照してください。

必須パラメーターはinputのみです。最大300 オブジェクトの配列です。 各オブジェクトには、挿入または更新するフィールドが含まれます。

次のオプションのパラメーターも含めることができます。

  • action: createOnly、updateOnlyまたはcreateOrUpdateを受け入れます。 省略した場合、モードはデフォルトでcreateOrUpdateになります。
  • dedupeBy: アクションがcreateOnlyまたはcreateOrUpdateに設定されている場合、idFieldまたはdedupeFieldsを受け入れます。 省略した場合、モードはデフォルトでdedupeFieldsになります。

dedupeByがidFieldの場合、説明に記載されているidFieldは重複排除に使用され、各レコードに含める必要があります。 idField モードは、createOnly モードと互換性がありません。

dedupeByがdedupeFieldsの場合、オブジェクトの説明にリストされている各dedupeFields フィールドをすべてのレコードに含めます。

フィールド値を渡すと、データベースは値nullまたは空の文字列をnullとして書き込みます。

POST /rest/v1/opportunities.json
{
   "action":"createOrUpdate",
   "dedupeBy":"dedupeFields",
   "input":[
      {
         "externalOpportunityId":"19UYA31581L000000",
         "name":"Chairs",
         "description":"Chairs",
         "amount":"1604.47",
         "source":"Inbound Sales Call/Email"
      },
      {
         "externalOpportunityId":"29UYA31581L000000",
         "name":"Big Dog Day Care-Phase12",
         "description":"Big Dog Day Care-Phase12",
         "amount":"1604.47",
         "source":"Email"
      }
   ]
}
{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "status":"updated",
         "marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb"
      },
      {
         "seq":1,
         "status":"created",
         "marketoGUID":"cff23271-f996-47d7-984f-f2676861b5fb"
      }
   ]
}

リード APIを除き、create呼び出しとupdate呼び出しは、result配列内の各オブジェクトのseq フィールドを返します。 この番号は、リクエスト内の更新されたレコードの位置に対応します。

各結果は、オブジェクトタイプのidField値と、「作成済み」、「更新」、「スキップ済み」のstatusも返します。 ステータスがスキップされた場合、結果には「reasons」配列が含まれます。 理由オブジェクトには、レコードがスキップされた理由を説明するコードとメッセージが含まれています。 詳しくは、​ エラーコード ​を参照してください。

削除

リードを除き、リードデータベースオブジェクトは標準の削除インターフェイスを使用します。 入力に加えて、必須パラメーターはidFieldまたは重複排除フィールドを受け入れるdeleteBy,のみです。

次の例では、カスタムオブジェクトを削除します。

POST /rest/v1/customobjects/{name}/delete.json
{
   "deleteBy":"dedupeFields",
   "input":[
      {
         "vin":"19UYA31581L000000"
      },
      {
         "vin":"29UYA31581L000000"
      },
      {
         "vin":"39UYA31581L000000"
      }
   ]
}
{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb",
         "status": "deleted"
      },
      {
         "seq":1,
         "marketoGUID":"da42707c-4dc4-4fc1-9fef-f30a3017240a",
         "status": "deleted"
      },
      {
         "seq":2,
         "status": "skipped"
         "reasons":[
            {
               "code":"1013",
               "message":"Object not found"
            }
         ]
      }
   ]
}

応答には、seq、statusおよびmarketoGUIDが含まれます。 スキップされたレコードの場合は、reasonsも含まれます。

特定のオブジェクトタイプのCRUD操作について詳しくは、そのオブジェクトのドキュメントを参照してください。

recommendation-more-help
marketo-developer-help