Salesforce 擴充功能

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件
資訊

版本:1.0.1

存取 Salesforce 帳戶中的資料。插入、更新、擷取及查詢資料。

這項內容提供設定與使用這項擴充功能的參考資源。

必要條件

這項內容提供設定與使用這項擴充功能的參考資源。透過 Extension 摘要政策使用 API Proxy 擴充功能之前,您必須:

  1. 建立 RSA x509 私密金鑰/認證組合。

    設定擴充功能時,您將使用私密金鑰 (.key) 做為憑證。在建立連結的應用程式時,您可以使用憑證 (.crt) 檔案將 Salesforce 存取權授予擴充功能。

    openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt
    
    
  2. 設定連結的應用程式。

    連結 Salesforce 的應用程式將為 Salesforce 擴充功能提供存取權,請參閱以下操作說明,瞭解如何設定應用程式。

  3. 取得已連結應用程式的用戶端金鑰。擴充功能向應用程式驗證時,會使用此內容。

    1. 在 Salesforce 設定中,前往左側導覽面板中的「應用程式」>「>」App Manager
    2. 在清單中找出您建立的連結應用程式。
    3. 在應用程式資料列的右側下拉式選單中,按一下「View」
    4. 在「API (啟用 OAuth 設定)」下方,找出「用戶端金鑰」,並將值複製到安全的地方,以供設定擴充功能時使用。

設定連結的應用程式,以便擴充功能存取

您必須先建立 Salesforce 連結應用程式,擴充功能才能透過 Salesforce 連結 Salesforce 來存取 Salesforce。

在 Salesforce 中,連結的應用程式可讓外部應用程式透過 API 連線至 Salesforce。

如何設定連結的應用程式

  1. 登入 Salesforce
  2. 按一下右上角的齒輪圖示,然後點選「設定」
  3. 在左側導覽面板中,展開 [應用程式] >App Manager
  4. 在「App Manager」頁面中,按一下「新增已連結的應用程式」
  5. 填寫「基本資訊」下方的必填欄位。這些價值與簿記價值有關但不會用於擴充功能
  6. 在「API (啟用 OAuth 設定)」下方,勾選「啟用 OAuth 設定」核取方塊。
  7. 雖然擴充功能未採用這個巨集,但請在欄位中輸入回呼網址。您可以使用 http://localhost/ 或其他預留位置主機。
  8. 勾選「使用數位簽名」核取方塊。
  9. 在「使用數位簽名」下方按一下「選擇檔案」,找出並上傳您先前產生的 salesforce.crt
  10. 在「選取的 OAuth 範圍」部分中新增下列內容,使其列在「選取的 OAuth 範圍」下方:
    • 存取及管理您的資料 (API)
    • 隨時代您執行要求 (refresh_token、Offline_access)
  11. 按一下 [儲存]。如有任何錯誤,您可能需要重新產生並上傳 salesforce.crt 檔案。
  12. 在顯示的應用程式中,按一下「管理」
  13. 在您剛建立的應用程式「App Manager」頁面中,按一下「編輯政策」
  14. 在「OAuth 政策」下方,按一下「許可的使用者」下拉式選單,然後點選「管理員已核准的使用者已預先授權」
  15. 按一下 [儲存]
  16. 返回應用程式頁面的「個人資料」下方的「管理個人資料」
  17. 在「應用程式設定檔指派」頁面上,找出可使用這個應用程式的使用者設定檔,然後勾選對應的核取方塊。

    請務必依據您要設定擴充功能的使用者名稱,選取對應的設定檔。同時確定至少有「系統管理員」使用者可以存取這個應用程式。

    您可以在 Salesforce 中查看使用者的設定檔設定。在「設定」區域中,展開「使用者」>使用者找出擴充功能所代表的使用者,然後在「個人資料」設定檔欄中找到他們的個人資料。

  18. 按一下 [儲存]

關於 Salesforce

Salesforce 是客戶關係管理平台。客戶關係管理可協助公司瞭解客戶而且只要透過一個平台,就能隨時透過任何電腦或裝置存取客戶資訊和互動資料,更有效地管理客戶資訊與互動,藉此解決問題。

動作

insert

sObject types 插入記錄。

語法

<Action>insert</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "records":[ records-to-insert ],
  "allOrNone": true | false
}]]></Input>

範例

<Action>insert</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "records":[
    { "Name": "MyAccountName" }
  ],
  "allOrNone": true
}]]></Input>

要求參數

參數 說明 類型 預設 必填
Sobject 要插入的記錄 sObject type 字串 無。 是。
記錄 JSON 格式的 sObject 記錄陣列。上限:1,000。 陣列 無。 是。
allOrNone 如果任何部分更新失敗,true 就會失敗整個更新。 布林值 false 編號

回應

含有插入作業結果的 results 陣列。

{
  results: [
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
屬性 說明 類型 預設 必填
results[*].id 為新記錄產生的 sObject ID。 字串 無。 是。
results[*].success true 表示成功插入記錄。 布林值 無。 是。
results[*].errors 在執行期間擷取的錯誤陣列 (如果有的話)。 陣列 無。 是。

update

更新 Salesforce 記錄。

語法

<Action>update</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "records": [ records-to-update ],
  "allOrNone": true | false
}]]></Input>

範例

<Action>update</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "records":[
    { 
      "id":"0011U00000LQ76KQAT",
      "Name": "MyNewAccountName" 
    }
  ],
  "allOrNone": true
}]]></Input>

要求參數

參數 說明 類型 預設 必填
Sobject 要更新的記錄 sObject type 字串 無。 是。
記錄 JSON 格式的 sObject 記錄陣列。每筆記錄的更新都必須包含該記錄的 ID 值。上限:1,000。 陣列 無。 是。
allOrNone 如果任何部分更新失敗,true 就會失敗整個更新。 布林值 false 編號

回應

包含更新結果的 results 陣列。

{
  results: [
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
參數 說明 類型 預設 必填
results[*].id 為更新記錄產生的 sObject ID。 字串 無。 是。
results[*].success true 表示成功插入記錄。 布林值 無。 是。
results[*].errors 在執行期間擷取的錯誤陣列 (如果有的話)。 陣列 無。 是。

retrieve

按 ID 擷取記錄做為 sObjects。傳回 sObject 類型的所有欄位。

語法

<Action>retrieve</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "ids":[ IDs-of-records-to-retrieve ]
}]]></Input>

範例

<Action>retrieve</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "ids":["0011U00000LQ76KQAT"]
}]]></Input>

要求參數

參數 說明 類型 預設 必填
Sobject 要擷取的記錄 sObject type 字串 無。 是。
ids 要擷取的 sObject ID 記錄陣列。上限:1,000。 陣列 無。 是。
allOrNone 如果要求的任何部分失敗,則 true 會導致整個作業失敗。 布林值 false 編號

回應

以 JSON 表示的 records sObjects 陣列。請注意,即使屬性值是空值,物件的所有屬性都會包含在 JSON 中。

{
  records: [
    { sobject-json },
    { sobject-json }
  ]
}

querySOQL

使用 Salesforce 物件查詢語言 (SOQL) 查詢 Salesforce.com。

語法

<Action>querySOQL</Action>
<Input><![CDATA[{
  "soql": soql-query-statement
}]]></Input>

範例

<Action>querySOQL</Action>
<Input><![CDATA[{
  "soql": "SELECT Id, Name FROM Account"
}]]></Input>

要求參數

參數 說明 類型 預設 必填
索克 要用於查詢的 SOQL 陳述式。 字串 無。 是。

回應

查詢結果。

{
  totalSize: 2,
  records: [
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76KQAT',
      Name: 'AccountName1'
    },
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76LQAT',
      Name: 'AccountName2'
    }
  ],
  done: true
}
參數 說明 類型 預設 必填
totalSize 查詢傳回的記錄數量。 整數 無。 是。
記錄 JSON 中以 sObjects 形式傳回的記錄陣列。上限:1,000。 陣列 無。 是。
完成 true 表示查詢作業已完成。 布林值 無。 是。

list

列出 Salesforce.com 記錄。傳回指定 sObject 類型的所有欄位。

語法

<Action>list</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "limit": max-number-of-records,
  "offset": record-index-at-which-to-begin-response-set
}]]></Input>

範例

<Action>list</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "limit": 1000,
  "offset": 0
}]]></Input>

要求參數

參數 說明 類型 預設 必填
Sobject 要列出的記錄的 sObject type 字串 無。 是。
限制 要傳回的記錄數量上限。 整數 1000 編號
碳補償 要列出的記錄偏移量。 整數 0 編號

回應

包含將 sObjects 列為 JSON 的 records 陣列。

{
  records: [
    { sobject-json },
    { sobject-json }
  ]
}

del

刪除含有指定 ID 的記錄。

語法

<Action>del</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "ids":[ IDs-of-records-to-retrieve ]
}]]></Input>

範例

<Action>del</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "ids":["0011U00000LQ76KQAT"]
}]]></Input>

要求參數

參數 說明 類型 預設 必填
Sobject 要刪除的記錄的 sObject type 字串 無。 是。
ids 要刪除的 sObject ID 陣列。上限:1,000。 陣列 無。 是。

回應

包含作業結果的 results 陣列。

{
  results:[
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
屬性 說明 類型 預設 必填
results[*].id 指定記錄的物件 ID。 字串 無。 是。
results[*].success true 表示作業成功完成記錄。 布林值 無。 是。
results[*].errors 在執行期間擷取的錯誤陣列 (如果有的話)。 陣列 無。 是。

getAccessToken

取得 Salesforce.com API 存取權杖。可用於查詢 REST API。

語法

<Action>getAccessToken</Action>
<Input><![CDATA[{}]]></Input>

要求參數

無。

回應

JSON 格式的存取權杖。

{
  "accessToken":"00D1U0000014m3hqswvoM22I5GTw9EJrztlZ8eSSka88Q",
  "scope":"api",
  "instanceUrl": "https://na85.salesforce.com",
  "id": "https://login.salesforce.com/id/00D1U0004564mutUAA/0051U43214qecVQAQ",
  "tokenType": "Bearer"
}
屬性 說明 類型 預設 必填
accessToken 存取權杖。 字串 無。 是。
範圍 權杖提供存取權的範圍。 字串 無。 是。
instanceUrl Salesforce 機構使用的執行個體網址。 字串 無。 是。
id 已連結應用程式的 ID。 字串 無。 是。
tokenType 存取權杖的類型。 字串 承載系統 是。

設定參考資料

設定及部署這項擴充功能以用於 API Proxy 時,請使用下列指令。

常見擴充功能屬性

每個擴充功能都有下列屬性。

屬性 說明 預設 必要
name 您要為這項擴充功能設定的名稱。 相容
packageName Apigee Edge 指定的擴充功能套件名稱。 相容
version 擴充功能的擴充功能套件版本號碼。 相容
configuration 您要新增的擴充功能專屬的設定值。請參閱「這個擴充功能套件的屬性」一文 相容

這個擴充功能套件的屬性

指定這個擴充功能專用的下列設定屬性值。

屬性 說明 預設 必填
授權伺服器網址 從 Salesforce 取得授權時使用的網址。通常為 https://login.salesforce.com 無。 是。
已連結的應用程式消費者金鑰 Salesforce 為您建立的已連結應用程式提供的用戶端金鑰。請參閱事前準備中的操作說明,瞭解如何擷取用戶端金鑰。 無。 是。
憑證

在 Apigee Edge 控制台中使用:您先前在「必要條件」下產生的 salesforce.key 檔案完整內容 (包括 BEGINEND 標記)。

透過 Management API 傳送時:從 salesforce.key 檔案產生的 Base64 編碼值。

無。 是。
Salesforce 使用者的使用者名稱 您已建立的連結應用程式相關聯的使用者名稱。Salesforce 擴充功能會使用這項資訊取得 Salesforce 授權。 無。 是。