機會角色

Last update: Mon Sep 29 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：

建立對象：

管理員

機會角色端點參考

潛在客戶透過中繼opportunityRole物件連結至商機。

機會角色API僅公開給未啟用原生CRM同步處理的訂閱。

說明

和機會一樣，說明呼叫和CRUD作業也會針對機會角色公開。

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和searchableFields與機會都有點不同。 dedupeFields實際上提供了複合金鑰，其中需要externalOpportunityId、leadId和role的所有三項。目的地執行個體中必須有識別碼欄位的機會和潛在客戶連結，才能成功建立記錄。對於searchableFields、marketoGUID、leadId和externalOpportunityId，它們都自己對查詢有效，並使用與Opportunities相同的模式，但有一個額外的選項可使用複合索引鍵進行查詢，這要求透過POST提交JSON物件，連同額外的查詢引數_method=GET。

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"
      }
   ]
}

這會產生與標準GET查詢相同的回應型別，只是用來提出要求的介面不同。

建立和更新

商機角色的介面與用來建立及更新商機記錄的介面相同。

POST /rest/v1/opportunities/roles.json

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalOpportunityId": "19UYA31581L000000",
         "leadId": 456783,
         "role": "Technical Buyer",
         "isPrimary": false
      },
      {
         "externalOpportunityId": "19UYA31581L000000",
         "leadId": 456784,
         "role": "Technical Buyer",
         "isPrimary": false
      }
   ]
}

{
   "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"
      }
   ]
}

刪除

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

POST /rest/v1/opportunities/roles/delete.json

{
   "deleteBy": "dedupeFields",
   "input": [
      {
        "externalOpportunityId": "19UYA31581L000000",
        "leadId": 456783,
        "role": "Technical Buyer"
      }
   ]
}

{
    "requestId": "10f7c#173264db42d",
    "result": [
        {
            "seq": 0,
            "marketoGUID": "dff23271-f996-47d7-984f-f2676861b5fb"
            "status": "deleted"
        }
    ]
    "success": true
}

逾時

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

recommendation-more-help

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