機會

Last update: Thu May 30 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：

建立對象：

undefined

Marketo公開API以供讀取、寫入、建立和更新商機記錄。在Marketo中，機會記錄會透過中繼機會角色物件連結至銷售線索和聯絡人記錄，因此機會可能會連結至許多個別銷售線索。這兩種物件型別都會透過API公開，而且就像大多數Lead Database物件型別一樣，它們都有相對應的Describe呼叫，這會傳回有關物件型別的中繼資料。

Opportunity API是訂閱的唯讀存取權，具有 SFDC同步或 Microsoft Dynamics同步已啟用。

說明

說明Opportunity記錄會遵循潛在客戶資料庫物件的標準模式。

GET /rest/v1/opportunities/describe.json

{
   "requestId":"185d6#14b51985ff0",
   "success":true,
   "result":[
      {
         "name":"opportunity",
         "displayName":"Opportunity",
         "createdAt":"2015-02-03T22:36:23Z",
         "updatedAt":"2015-02-03T22:36:24Z",
         "idField":"marketoGUID",
         "dedupeFields":[
            "externalOpportunityId"
         ],
         "searchableFields":[
            [
               "externalOpportunityId"
            ],
            [
               "marketoGUID"
            ]
         ],
         "fields":[
            {
               "name":"marketoGUID",
               "displayName":"Marketo GUID",
               "dataType":"string",
               "length":36,
               "updateable":false
            },
            {
               "name":"createdAt",
               "displayName":"Created At",
               "dataType":"datetime",
               "updateable":false
            },
            {
               "name":"updatedAt",
               "displayName":"Updated At",
               "dataType":"datetime",
               "updateable":false
            },
            {
               "name":"externalOpportunityId",
               "displayName":"External Opportunity Id",
               "dataType":"string",
               "length":50,
               "updateable":false
            }
         ]
      }
   ]
}

此回應型別最重要的欄位包括 idField， dedupeFields、和 searchableFields. idField會指出機會的主要索引鍵marketoGUID。這是系統產生的唯一索引鍵，可用於讀取和更新操作，但不能用於插入，因為它由系統管理。 dedupeFields陣列指出哪些欄位是插入作業的有效金鑰；在機會的情況下，這只有externalOpportunityId。 searchableFields陣列提供您一組有效的欄位，可用於查詢、externalOpportunityId和marketoGUID。

查詢

的模式查詢商機密切遵循銷售機會API的規則，新增限制： filterType 引數接受列在 searchableFields 陣列或對應的描述呼叫或dedupeFields。請注意，如果您使用自訂機會欄位，只有String或Integer型別的自訂機會欄位會列在searchableFields陣列中。

GET /rest/v1/opportunities.json?filterType=marketoGUID&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"
      }
   ]
}

您也可以包含選用的查詢引數 fields，以傳回其他機會欄位， nextPageToken，用於分頁比批次大小大的集合， batchSize，預設為，最多為300個。請求清單時 fields，如果要求特定欄位但未傳回，則值會隱含為空值。

建立和更新

機會會密切遵循潛在客戶API模式，但有一些限制。可用的值 action 為：createOnly、createOrUpdate和updateOnly。使用createOnly或createOrUpdate模式時，externalOpportunityId欄位必須包含在每個記錄中。對於updateOnly模式，可能會使用marketoGUID或externalOpportunityId。如果未指定，模式會預設為createOrUpdate。

此 lookupField 銷售機會API中的引數無法使用，且被dedupeBy引數取代，這只有在動作為updateOnly時有效。 dedupeBy可用的值是"dedupeFields"或"idField"，這兩個值分別由描述呼叫指定為externalOpportunityId和marketoGUID。如果未指定dedupeBy，預設為dedupeFields模式。 'name'欄位不可為Null。

您一次最多可以提交300筆記錄。

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會以回應 marketoGUID 每個記錄，以及 status 欄位，指示每個記錄的個別成功或失敗，以及 seq 用於將提交的記錄與回應順序關聯的欄位。欄位中的數字是請求中提交的記錄索引。

欄位

公司物件包含一組欄位。每個欄位定義都由一組描述該欄位的屬性組成。屬性的範例為顯示名稱、API名稱和dataType。這些屬性統稱為中繼資料。

下列端點可讓您查詢公司物件上的欄位。這些API要求擁有的API使用者必須具備具備以下一項或兩項的角色： Read-Write Schema Standard Field 或 Read-Write Schema Custom Field 許可權。

查詢欄位

查詢機會欄位非常簡單。您可以依API名稱查詢單一公司欄位，或查詢所有公司欄位集。

依名稱

此依名稱取得機會欄位端點會擷取公司物件上單一欄位的中繼資料。必要的 fieldApiName path引數指定欄位的API名稱。回應類似於Describe Opportunity端點，但包含其他中繼資料，例如 isCustom 表示欄位是否為自訂欄位的屬性。

GET /rest/v1/opportunities/schema/fields/externalOpportunityId.json

{
    "requestId": "12331#17e9779cb4b",
    "result": [
        {
            "displayName": "SFDC Oppty Id",
            "name": "externalOpportunityId",
            "description": null,
            "dataType": "string",
            "length": 50,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        }
    ],
    "success": true
}

瀏覽

此取得機會欄位端點會擷取公司物件上所有欄位的中繼資料。依預設，最多會傳回300筆記錄。您可以使用 batchSize 查詢引數以縮小此數目。如果 moreResult attribute為true，表示有更多結果可用。繼續呼叫此端點，直到moreResult屬性傳回false （表示沒有可用的結果）。此 nextPageToken 從此API傳回的應一律重複用於此呼叫的下一個反複專案。

GET /rest/v1/opportunities/schema/fields.json?batchSize=5

{
    "requestId": "b4a#17e995b31da",
    "result": [
        {
            "displayName": "SFDC Oppty Id",
            "name": "externalOpportunityId",
            "description": null,
            "dataType": "string",
            "length": 50,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Name",
            "name": "name",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Description",
            "name": "description",
            "description": null,
            "dataType": "string",
            "length": 2000,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Type",
            "name": "type",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Stage",
            "name": "stage",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        }
    ],
    "success": true,
    "nextPageToken": "E5ZONGE4SAHALYYW6FS25KB5BM======",
    "moreResult": true
}

刪除

您可以依重複資料刪除欄位或ID欄位來刪除商機。使用 deleteBy 具有dedupeFields或idField值的引數。如果未指定，預設值為dedupeFields。請求內文包含 input 要刪除的機會陣列。每個呼叫最多允許300個機會。

POST /rest/v1/opportunities/delete.json

{
   "deleteBy":"dedupeFields",
   "input":[
      {
         "externalOpportunityId":"19UYA31581L000000"
      },
      {
         "externalOpportunityId":"29UYA31581L000000"
      }
   ]
}

{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb",
         "status":"deleted"
      },
      {
         "seq":1,
         "marketoGUID":"cff23271-f996-47d7-984f-f2676861b5fb",
         "status":"deleted"
      }
   ]
}

逾時

機會端點的逾時為30秒，除非以下說明
- 同步處理機會：60秒
- 刪除機會：60秒

recommendation-more-help

bb269a6d-047a-4bf7-9acd-23ad9a63dc59