リードデータベース
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操作について詳しくは、そのオブジェクトのドキュメントを参照してください。