Salesforce 擴充功能

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

版本：2.0.2

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

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

必要條件

這項內容提供設定及使用這項擴充功能的參考資料。使用 ExtensionCallout 政策從 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 設定的左側導覽面板中，依序前往「應用程式」>「應用程式管理員」。
    2. 在清單中找出您建立的已連結應用程式。
    3. 在應用程式列右側的下拉式選單中，按一下「查看」。
    4. 在「API (Enable OAuth Settings)」下方，找出「Consumer Key」並複製其值，以便在設定擴充功能時使用。

設定連結的應用程式，供擴充功能存取

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

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

如何設定連結的應用程式

  1. 登入 Salesforce。
  2. 按一下右上角的齒輪圖示，然後點選「設定」。
  3. 在左側導覽中，展開「應用程式」>「應用程式管理工具」。
  4. 在「應用程式管理工具」頁面中，按一下「新增已連結的應用程式」。
  5. 在「基本資訊」下方，填寫必填欄位。這些值僅供記帳使用，擴充功能不會用到。
  6. 在「API (Enable OAuth Settings)」下方，選取「Enable OAuth Settings」核取方塊。
  7. 雖然擴充功能不會使用回呼網址，但請輸入回呼網址。您可以使用 http://localhost/ 或其他預留位置主機。
  8. 勾選「使用數位簽章」核取方塊。
  9. 在「使用數位簽章」下方，按一下「選擇檔案」，找出並上傳您先前產生的 salesforce.crt。
  10. 在「選取的 OAuth 範圍」部分，新增下列項目，讓這些項目顯示在「選取的 OAuth 範圍」下方：
    • 存取及管理資料 (API)
    • 隨時以您的名義執行要求 (refresh_token、offline_access)
  11. 按一下 [儲存]。如有任何錯誤，你可能需要重新產生並上傳 salesforce.crt 檔案。
  12. 在隨即顯示的應用程式頁面上，按一下「管理」。
  13. 在您剛建立的應用程式的「應用程式管理工具」頁面中，按一下「編輯政策」。
  14. 在「OAuth policies」下方，按一下「Permitted Users」下拉式選單，然後點選「Admin approved users are pre-authorized」。
  15. 按一下 [儲存]。
  16. 返回應用程式頁面，然後按一下「設定檔」下方的「管理設定檔」。

  17. 在「應用程式設定檔指派」頁面中，選取可使用這個應用程式的使用者設定檔核取方塊。

    請務必選取與設定擴充功能時所用使用者名稱相符的設定檔。此外，也請確認至少系統管理員使用者有權存取這個應用程式。

    您可以在 Salesforce 中查看使用者的設定檔設定。在「設定」區域中，依序展開「使用者」>「使用者」，找出擴充功能代表的使用者，然後在「設定檔」欄中找出該使用者的設定檔。

  18. 按一下 [儲存]。

關於 Salesforce

Salesforce 是客戶關係管理 (CRM) 平台，客戶關係管理系統可協助公司管理客戶資訊和互動，進一步瞭解客戶需求並解決問題，而且只要透過任何電腦或裝置，隨時都能存取這個單一平台。

動作

insert

以 sObject 類型插入記錄。

語法

<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 類型。 字串 無。 是。
記錄 JSON 格式的 sObject 記錄陣列。上限為 1000。 陣列 無。 是。
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 類型。 字串 無。 是。
記錄 JSON 格式的 sObject 記錄陣列。如要更新記錄，每筆記錄都必須包含記錄的 ID 值。上限為 1000。 陣列 無。 是。
allOrNone true：如果更新的任何部分失敗，整個更新作業就會失敗。 布林值 false 不會。

回應

包含更新結果的 results 陣列。

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

擷取

依 ID 將記錄擷取為 sObject。傳回 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 類型。 字串 無。 是。
ids 要擷取的 sObject ID 記錄陣列。上限為 1000。 陣列 無。 是。
allOrNone true：如果要求的任何部分失敗，整個作業就會失敗。 布林值 false 不會。

回應

以 JSON 表示的 sObject records 陣列。請注意，即使屬性值為空值，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 用於查詢的 SOQL 陳述式。 字串 無。 是。

回應

查詢結果。

{
  totalSize: 2,
  records: [
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76KQAT',
      Name: 'AccountName1'
    },
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76LQAT',
      Name: 'AccountName2'
    }
  ],
  done: true
}
參數 說明 類型 預設 必填
totalSize 查詢傳回的記錄數量。 整數 無。 是。
記錄 以 JSON 格式傳回 sObject 的記錄陣列。上限為 1000。 陣列 無。 是。
完成 如果查詢作業完成，則為 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 類型。 字串 無。 是。
限制 要傳回的記錄數上限。 整數 1000 不會。
碳補償 要列出的記錄偏移。 整數 0 不會。

回應

包含列出 sObject 的 records 陣列 (以 JSON 格式表示)。

{
  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 類型。 字串 無。 是。
ids 要刪除的記錄 sObject ID 陣列。上限為 1000。 陣列 無。 是。

回應

包含作業結果的 results 陣列。

{
  results:[
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
屬性 說明 類型 預設 必填
results[*].id 指定記錄的 sObject 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 存取權杖的類型。 字串 Bearer 是。

設定參考資料

設定及部署這個擴充功能，以便在 API Proxy 中使用時，請按照下列步驟操作。

常見的擴充功能屬性

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

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

這個擴充套件的屬性

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

屬性 說明 預設 必填
授權伺服器網址 從 Salesforce 取得授權時使用的網址。通常是 https://login.salesforce.com 無。 是。
已連線應用程式的消費者金鑰 Salesforce 為您建立的連結應用程式提供的消費者金鑰。如要擷取消費者金鑰，請參閱「必要條件」一節的操作說明。 無。 是。
憑證 在 Apigee Edge 控制台中輸入時，這是您在步驟中產生的 salesforce.key 檔案內容。透過 Management API 傳送時，這是從 salesforce.key 檔案產生的 base64 編碼值。 無。 是。
Salesforce 使用者名稱 與您建立的連結應用程式相關聯的使用者名稱。Salesforce 擴充功能會使用這項資訊，向 Salesforce 取得授權。 無。 是。