您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
版本:1.0.3
存取 Salesforce 帳戶中的資料。插入、更新、擷取及查詢資料。
本文提供設定和使用這個擴充功能的參考資料。
必要條件
本文提供設定和使用這個擴充功能的參考資料。透過 Extension callout 政策透過 API Proxy 使用擴充功能前,您必須:
建立 RSA x509 私密金鑰/認證組合。
您在設定擴充功能時,會使用私密金鑰 (.key) 做為憑證。建立的連結應用程式會將 Salesforce 存取權授予擴充功能時,您就需要使用憑證 (.crt) 檔案。
openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt
-
與 Salesforce 連結的應用程式會提供 Salesforce 擴充功能的存取權。請參閱以下操作說明,瞭解如何設定應用程式。
取得已連結應用程式的用戶端金鑰。擴充功能會在驗證應用程式時使用。
- 在 Salesforce 設定的左側導覽面板中,依序前往「應用程式」>「App Manager」。
- 在清單中,找出您建立的連結應用程式。
- 在應用程式列的右側下拉式選單中,按一下「查看」。
- 在「API (啟用 OAuth 設定)」下方找出「用戶端金鑰」,並將其值複製到設定擴充功能時的安全位置。
設定連結的應用程式,供擴充功能存取
您必須先建立 Salesforce 連結的應用程式,這個擴充功能可透過 Salesforce 連結,才能存取 Salesforce 擴充功能。
在 Salesforce 中,連結的應用程式可讓外部應用程式透過 API 連線至 Salesforce。
如何設定連結的應用程式
- 登入 Salesforce。
- 按一下右上角的齒輪圖示,然後點選「設定」。
- 在左側導覽面板中,依序展開「應用程式」>「應用程式管理員」。
- 在「App Manager」頁面中,按一下「新增連結的應用程式」。
- 填寫「Basic Information」下方的必填欄位。這些值僅供簿記,不會用於擴充功能。
- 在「API (啟用 OAuth 設定)」下方,勾選「啟用 OAuth 設定」核取方塊。
- 雖然額外資訊沒有使用這個參數,但請輸入「回呼網址」。您可以使用
http://localhost/
或其他預留位置主機。 - 勾選「使用數位簽章」核取方塊。
- 按一下「使用數位簽章」下方的「選擇檔案」,找出並上傳您先前產生的
salesforce.crt
。 - 在「已選取的 OAuth 範圍」部分新增下列內容,將這些範圍列在「已選取的 OAuth 範圍」底下:
- 存取及管理您的資料 (API)
- 隨時代表您執行要求 (refresh_token、Offline_access)
- 按一下「儲存」,如有任何錯誤,您可能需要重新產生並上傳
salesforce.crt
檔案。 - 在隨即顯示的應用程式頁面中,按一下「管理」。
- 在剛建立的應用程式「應用程式管理員」頁面中,按一下「編輯政策」。
- 在「OAuth 政策」下方,點選「許可的使用者」下拉式選單,然後點選「管理員核准的使用者是否獲得預先授權」。
- 點按「儲存」。
- 返回應用程式頁面,然後在「個人資料」下方點選「管理個人資料」。
在「應用程式設定檔指派」頁面中,勾選可使用這個應用程式的使用者設定檔核取方塊。
請務必根據設定擴充功能時使用的使用者名稱,選取該使用者對應的設定檔。同時確認至少有系統管理員使用者有權存取這個應用程式。
您可以在 Salesforce 中查看使用者的個人資料設定。在「設定」區域中,展開「使用者」>「使用者」,找出擴充功能代表的使用者,然後在「設定檔」欄中找出其設定檔。
點按「儲存」。
關於 Salesforce
Salesforce 是客戶關係管理 (CRM) 平台,客戶關係管理服務有助於公司瞭解客戶的需求並解決問題,也就是提供更完善的客戶資訊和互動管理方式,而且這些平台隨時可以透過任何電腦或裝置存取。
動作
insert
以 sObject type 格式插入記錄。
語法
<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 類型。 | 字串 | 無。 | 可以。 |
records | JSON 中的 sObject 記錄陣列。上限:1,000。 | 陣列 | 無。 | 可以。 |
allOrNone | 如果有任何部分更新失敗,true 會使整個更新作業失敗。 |
布林值 | false | 不會。 |
回應
包含插入作業結果的 results
陣列。
{
results: [
{ id: '0011U00000LQ76KQAT', success: true, errors: [] },
{ id: '0011U00000LQ76LQAT', success: true, errors: [] }
]
}
屬性 | 說明 | 類型 | 預設 | 需要 |
---|---|---|---|---|
results[*].id | 為新記錄產生的 sObject ID。 | 字串 | 無。 | 可以。 |
結果 [*].success | true (如果插入成功的話)。 |
布林值 | 無。 | 可以。 |
結果 [*].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 類型。 | 字串 | 無。 | 可以。 |
records | JSON 中的 sObject 記錄陣列。每筆要更新的記錄都必須包含記錄的 ID 值。上限:1,000。 | 陣列 | 無。 | 可以。 |
allOrNone | 如果有任何部分更新失敗,true 會使整個更新作業失敗。 |
布林值 | false | 不會。 |
回應
包含更新結果的 results
陣列。
{
results: [
{ id: '0011U00000LQ76KQAT', success: true, errors: [] },
{ id: '0011U00000LQ76LQAT', success: true, errors: [] }
]
}
參數 | 說明 | 類型 | 預設 | 需要 |
---|---|---|---|---|
results[*].id | 為更新記錄產生的 sObject ID。 | 字串 | 無。 | 可以。 |
結果 [*].success | true (如果插入成功的話)。 |
布林值 | 無。 | 可以。 |
結果 [*].errors | 執行期間出現的錯誤陣列 (如果有的話)。 | 陣列 | 無。 | 可以。 |
retrieve
以 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 類型。 | 字串 | 無。 | 可以。 |
ids | 要擷取的 sObject ID 記錄陣列。上限:1,000。 | 陣列 | 無。 | 可以。 |
allOrNone | 如果要求的任何部分失敗,true 就會讓整個作業失敗。 |
布林值 | false | 不會。 |
回應
以 JSON 表示的 sObjects 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 陳述式。 | 字串 | 無。 | 可以。 |
回應
查詢結果。
{
totalSize: 2,
records: [
{
attributes: { attributes-of-record },
Id: '0011U00000LQ76KQAT',
Name: 'AccountName1'
},
{
attributes: { attributes-of-record },
Id: '0011U00000LQ76LQAT',
Name: 'AccountName2'
}
],
done: true
}
參數 | 說明 | 類型 | 預設 | 需要 |
---|---|---|---|---|
totalSize | 查詢傳回的記錄數量。 | 整數 | 無。 | 可以。 |
records | 以 JSON 格式傳回的記錄陣列。上限: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 類型。 | 字串 | 無。 | 可以。 |
限制 | 要傳回的記錄數量上限。 | 整數 | 1000 | 不會。 |
碳補償 | 要列出的記錄偏移值。 | 整數 | 0 |
不會。 |
回應
包含以 JSON 格式列出 sObjects 的 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 類型。 | 字串 | 無。 | 可以。 |
ids | 要刪除的記錄的 sObject ID 陣列。上限:1,000。 | 陣列 | 無。 | 可以。 |
回應
包含作業結果的 results
陣列。
{
results:[
{ id: '0011U00000LQ76KQAT', success: true, errors: [] },
{ id: '0011U00000LQ76LQAT', success: true, errors: [] }
]
}
屬性 | 說明 | 類型 | 預設 | 需要 |
---|---|---|---|---|
results[*].id | 指定記錄的物件 ID。 | 字串 | 無。 | 可以。 |
結果 [*].success | true 表示作業成功。 |
布林值 | 無。 | 可以。 |
結果 [*].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 檔案內容。透過 Management API 傳送時,是從 Salesforce.key 檔案產生的 Base64 編碼值。 | 無。 | 可以。 |
Salesforce 使用者的使用者名稱 | 與您建立的連結應用程式相關聯的使用者名稱。Salesforce 擴充功能會使用這個擴充功能取得 Salesforce 授權。 | 無。 | 可以。 |