外部服務 OpenAPI 2.0 結構描述
此區段包含外部服務 OpenAPI 2.0 結構描述的範例。
必要版本
| 提供版本：Lightning Experience |
| 提供版本：Enterprise、Performance、Unlimited 及 Developer Edition |
範例 1：包含要求與回應的基本 OpenAPI 規格 (OAS 2.0)
以下是 API 規格的範例,其中包含 OpenAPI 2.0 支援的 JSON 結構描述。參數 (粗體) 包含 accountId 輸入的定義。回應 (也以粗體顯示) 包含輸出的定義,即 creditRating。參數與回應會分別針對您的流程動作轉換為輸入與輸出。
{
"swagger":"2.0",
"info":{
"description":"A service for checking credit for an account.",
"version":"1.0.0",
"title":"Credit Decision",
"termsOfService":"http://swagger.io/terms/",
"contact":{
"email":"apiteam@swagger.io"
},
"license":{
"name":"Apache 2.0",
"url":"http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host":"<YourHostName>",
"paths":{
"/account/lastCreditRating":{
"get":{
"summary":"Evaluates credit rating and decides what payment terms to offer.",
"description":"",
"consumes":[
"application/json",
"application/xml"
],
"produces":[
"application/xml",
"application/json"
],
"parameters":[{
"in":"body",
"name":"body",
"description":"Specifies input parameters to calculate payment term",
"required":true,
"schema":{
"$ref":"#/definitions/accountId"
}
}],
"responses":{
"200":{
"description":"success",
"schema":{
"$ref":"#/definitions/creditRating"
}
},
"405":{
"description":"Invalid input"
}
}
}
}
},
"definitions":{
"accountId":{
"type":"object",
"properties":{
"accountIdString":{
"type":"string"
}
},
"xml":{
"name":"accountId"
}
},
"creditRating":{
"type":"object",
"properties":{
"creditRatingString":{
"type":"string"
}
},
"xml":{
"name":"creditRating"
}
}
}
}範例 2：具名物件結構描述參考 (OAS 2.0)
基本設定
- 在您組織用來存取銀行系統的已命名認證中，指派 Bank 標籤和預留位置 URL (如 https://api.example.com)。使用 example.com，因為您將在註冊時間中貼至結構描述，而非使用 URL 以指向 API 規格。
- 註冊員工銀行系統的外部服務。使用 Bank 名稱和 Bank 已命名認證，然後複製並貼至下列結構描述。
- 銀行系統外部服務會顯示兩個使用物件類型定義參數的方法：在「定義」區塊或內嵌匿名宣告的物件類型下具名的物件類型。
備註 定義或衍生參數物件類型名稱，或類型為物件的內容，其長度必須少於 255 個字元才能在 Apex 或 Flow Builder 中使用。
以下是 JSON 格式的結構描述,其中已在 「定義 」區塊下定義具名物件類型。電話物件類型的名稱是 Apex 或 Flow Builder 中的 ExternalService__Bank_Phone。
{
"swagger": "2.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"User": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones":{
"type":"array",
"items":{
"type": "object",
"$ref": "#/definitions/Phone"
}
}
}
},
"Phone":{
"properties":{
"typeofphone":{
"type":"string"
},
"phone":{
"type":"string"
}
}
}
},
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [{
"in": "path",
"name": "userId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"parameters": [{
"in": "body",
"name": "user",
"schema": {
"$ref": "#/definitions/User"
}
}],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}以下是相同的結構描述,但格式為 YAML。
swagger: '2.0'
info:
title: bankService
description: API description in Markdown.
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
definitions:
User:
properties:
id:
type: integer
name:
type: string
phones:
type: array
items:
type: object
$ref: '#/definitions/Phone'
Phone:
properties:
typeofphone:
type: string
phone:
type: string
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
'200':
description: OK
schema:
$ref: '#/definitions/User'
/users:
post:
summary: Creates a new user.
parameters:
- in: body
name: user
schema:
$ref: '#/definitions/User'
responses:
'200':
description: OK
範例 3：巢狀匿名物件結構描述 (OAS 2.0)
以下的 API 規格具有 JSON 結構描述，其中含內嵌定義的匿名物件類型。衍生的電話物件類型名稱為 ExternalService__Bank_getUsers_OUT_200_phones。
備註 在匿名物件類型中，Salesforce 會自動根據外部服務、父系作業、作業參數、父系物件和物件內容名稱來自動衍生物件類型名稱。衍生名稱必須少於 255 個字元。如需詳細資訊,請參閱 外部服務考量事項中的「外部服務 Apex 類別名稱和開發人員名稱」。
{
"swagger": "2.0",
"info": {
"title": "bankService",
"description": "API description in Markdown.",
"version": "1.0.0"
},
"host": "api.example.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/users/{userId}": {
"get": {
"summary": "Returns a user by ID.",
"parameters": [{
"in": "path",
"name": "userId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"type": "object",
"properties": {
"typeofphone": {
"type":"string"
},
"phone": {
"type":"string"
}
}
}
}
}
}
}
}
}
},
"/users": {
"post": {
"summary": "Creates a new user.",
"parameters": [{
"in": "body",
"name": "user",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"type": "object",
"properties": {
"typeofphone": {
"type":"string"
},
"phone": {
"type":"string"
}
}
}
}
}
}
}],
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}範例 4：Apex 物件類別命名 (OAS 2.0)
以下的 API 規格是以外部服務名稱 BankingAutomaticTellerMachine 註冊的。然而，衍生名稱必須少於 255 個字元。
- ExternalService__BankingAutomaticTellerMachine_VeryImportantCustomer_phone
- ExternalService__BankingAutomaticTellerMachine_getBalanceAccountTypeChecking_OUT_200
若要使用 Apex 或 Flow Builder，您必須縮短外部服務的結構描述名稱和結構描述 (顯示於範例 5)。
小秘訣 如果衍生物件名稱長於 255 個字元，請嘗試以下其中一個方法來解決問題。
- 縮短外部服務名稱。
- 如果在作業參數下宣告此物件，請將 operationId 新增至結構描述來縮短作業名稱。
- 如果在父系物件內容下內嵌宣告此物件，請在結構描述中縮短此父系物件的名稱。
- 在結構描述「定義」下將巢狀物件宣告為最上層物件。
{
"swagger": "2.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"parameters": [{
"in": "path",
"name": "accountId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/definitions/VeryImportantCustomer"
}
}
}
}
}
}
}
},
"definitions": {
"VeryImportantCustomer": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}範例 5：縮短 Apex 物件類別命名 (OAS 2.0)
以下為 API 規格範例，範例中的規格具有會導致名稱縮短的結構描述。其使用縮短的名稱 BankAtm 來註冊。
將外部服務結構描述名稱縮短為 BankAtm，結構描述物件名稱為 VIP 並新增 operationId 作為 getBalance：
- ExternalService__BankAtm_VIP_phone
- ExternalService__BankAtm_getBalance_200
{
"swagger": "2.0",
...
"paths": {
"/balance/account/{accountId}/type/checking": {
"get": {
"operationId": "getBalance",
"parameters": [{
"in": "path",
"name": "accountId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"owner": {
"$ref": "#/definitions/VIP"
}
}
}
}
}
}
}
},
"definitions": {
"VIP": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"phone": {
"type": "object",
"properties": {
"number": {
"type": "string"
}
}
}
}
}
}
}範例 6：內嵌陣列 (OAS 2.0)
以下是具有內嵌陣列定義的範例。
{
"swagger": "2.0",
"host": "Employees.org",
"basePath": "/",
...
"paths": {
"/employees/{employeeId}": {
"get": {
"operationId": "getEmployee",
"parameters": [{
"in": "path",
"name": "employeeId",
"required": true,
"type": "string"
}],
"responses": {
"200": {
"schema": {
"type": "object",
"properties": {
"employee": {"$ref": "#/definitions/Employee"},
"manager": {"$ref": "#/definitions/Employee"},
"team": {
"type": "array",
"items": {"$ref": "#/definitions/Employee"}
}
}
}
}
}
}
}
},
"definitions": {
"Employee" : {
"type": "object",
"properties": {
"employeeId": {"type": "string"},
"firstName": {"type": "string"},
"middleName": {"type": "string"},
"lastName": {"type": "string"},
"dateOfHire": {"type": "date"}
}
}
}
}
}
範例 7：HTTP 標頭參數 (OAS 2.0)
以下是在 OpenAPI 結構描述中宣告標頭參數的方法。在 Apex 或流程中,名稱「apiKey」會顯示為字串參數。現在,當您將 Apex 或流程中的任何字串值設定為 apiKey 時,它會在提出呼叫要求時作為 HTTP 參數運作。
{
"swagger": "2.0",
"info": {
"description": "A service for checking credit for an account.",
"version": "1.0.0",
"title": "Credit Decision",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"email": "apiteam@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"host": "<YourHostName>",
"paths": {
"/account/lastCreditRating": {
"get": {
"summary": "Evaluates credit rating and decides what payment terms to offer.",
"description": "",
"consumes": [
"application/json",
"application/xml"
],
"produces": [
"application/xml",
"application/json"
],
"parameters": [{
"name": "body",
"description": "Specifies input parameters to calculate payment term",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/accountId"
}
},{
"name": "apiKey",
"description": "Your API Key for calling the credit rating service",
"in": "header",
"type": "string"
}],
"responses": {
"200": {
"description": "success",
"schema": {
"$ref": "#/definitions/creditRating"
}
},
"405": {
"description": "Invalid input"
}
}
}
}
},
"definitions": {
"accountId": {
"type": "object",
"properties": {
"accountIdString": {
"type": "string"
}
},
"xml": {
"name": "accountId"
}
},
"creditRating": {
"type": "object",
"properties": {
"creditRatingString": {
"type": "string"
}
},
"xml": {
"name": "creditRating"
}
}
}
}範例 8：URL 編碼表單媒體類型 (OAS 2.0)
系統會將要求與回應表單資料與相符的 consumes 與 produces 指示詞一起宣告。
{
"swagger": "2.0",
"info": {
"description": "Apply here for your next mortgage",
"version": "1.0.0",
"title": "My Mortgage Buddy",
"contact": {
"email": "apiteam@swagger.io"
}
},
"host": "MyMortgageBuddy.org",
"basePath": "/mortgages",
"paths": {
"/apply": {
"post": {
"operationId": "applyMortgage",
"consumes": [
"application/x-www-form-urlencoded; charset=utf-8"
],
"produces": [
"application/x-www-form-urlencoded; charset=utf-8"
],
"parameters": [{
"description": "Desired mortgage terms",
"name": "terms",
"in": "formData",
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "multi",
"required": true
},{
"description": "Full Name",
"name": "fullName",
"in": "formData",
"type": "string",
"required": true
},{
"description": "Loan amount",
"name": "loanAmount",
"in": "formData",
"type": "number",
"required": true
}],
"responses": {
"200": {
"description": "200",
"schema": {
"type": "object",
"properties": {
"formApplicationId": {
"type": "string"
},
"loanOfficerFullName": {
"type": "string"
}
}
}
}
}
}
}
}
}
範例 9：allOf 和 additionalProperties 結構描述指示詞 (OAS 2.0)
此 JSON 結構描述定義會醒目提示結構描述物件組成的建構 allOf,以及字典值的 additionalProperties。範例結構描述會註冊為含已命名認證 MyBank 的外部服務 MyBank。註冊會由使用 Apex 可叫用動作存取字典內容的範例流程叫用。流程 Apex 單元測試會將項目全部繫結在一起。
結構描述會定義銀行服務，以針對客戶識別碼取得客戶詳細資料。
Customer結構描述物件具有類型結構描述物件CreditRating的字典內容。在 Apex 中,類別ExternalService.MyBank_Customer具有屬性properties,類型為Map<String, ExternalService_CreditRating>與客戶的信用評等。- 電話與電子郵件會撰寫自己的內容,以及結構描述物件
Contact.中的常見allOf內容
{
"swagger": "2.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and additionalProperties schema constructs",
"version": "1.0.0"
},
"host": "api.mybank.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"phones": {
"type":"array",
"items": {
"$ref": "#/definitions/Phone"
}
},
"emails": {
"type": "array",
"items": {
"$ref": "#/definitions/Email"
}
}
},
"additionalProperties": {
"$ref": "#/definitions/CreditRating"
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"properties": {
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type":"string"
},
"phoneNumber":{
"type":"string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type":"string"
}
}
}
]
},
"CreditRating": {
"type": "object",
"properties": {
"rating": {
"type": "string"
},
"score": {
"type": "number",
"format": "double"
}
}
}
},
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [{
"in": "path",
"name": "customerId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Customer"
}
}
}
}
}
}
}若要使用 allOf 組成和 additionalProperties,請參閱 範例 9:在包含 Apex 單元測試的流程中使用的 allOf 組成和 additionalProperties。
範例 10：allOf 和 discriminator 指示詞 (OAS 2.0)
若要為客戶指定一般可擴充的連絡人清單,可以將 discriminator 指示詞與 allOf 結合,以宣告連絡人是電子郵件還是電話號碼:
{
"swagger": "2.0",
"info": {
"title": "myBank",
"description": "Sample Banking Service with allOf and discriminator",
"version": "1.0.0"
},
"host": "api.mybank.com",
"basePath": "/v1",
"schemes": [
"https"
],
"definitions": {
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"contacts": {
"type":"array",
"items": {
"$ref": "#/definitions/Contact"
}
}
},
"required": [
"id",
"name"
]
},
"Contact": {
"type": "object",
"discriminator": "contactType",
"properties": {
"contactType": {
"type": "string"
},
"primary": {
"type": "boolean"
},
"timeOfDay": {
"type": "string"
}
},
"required": [
"contactType",
"primary"
]
},
"Phone": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"typeOfPhone": {
"type":"string"
},
"phoneNumber":{
"type":"string"
}
}
}
]
},
"Email": {
"allOf": [
{
"$ref": "#/definitions/Contact"
},
{
"type": "object",
"properties": {
"email": {
"type":"string"
}
}
}
]
}
},
"paths": {
"/customers/{customerId}": {
"get": {
"summary": "Get the customer by ID.",
"parameters": [{
"in": "path",
"name": "customerId",
"required": true,
"type": "integer"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Customer"
}
}
}
}
}
}
}
若要使用組成和多型 OpenAPI 結構描述建構,請參閱 範例 10:含 allOf 和 Discriminator 的多型。
陣列定義 (OAS 2.0)
外部服務支援內嵌陣列定義和可參照的具名陣列。外部服務中的清單類型可透過其物件元素類型來識別。
參照陣列項目定義之支援的內嵌陣列定義
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"$ref": "#definitions/MyObject"
}
}
...
"definitions": {
"MyObject": {
"type": "object",
"properties": {...}
}
}
}在 Apex 和 Flow Builder 中,將變數標記為集合並挑選其 Apex 元素類型 ExternalService__RegistrationName_MyObject,以宣告 myObjects 參數的變數。
內嵌陣列定義與內嵌陣列項目定義
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
...
"definitions": {
...
}
}在 Apex 與 Flow Builder 中,宣告 myObjects 參數和 Apex 元素類型 ExternalService__RegistrationName_OperationName_IN_myObjects 的集合變數。
可參照的陣列定義與陣列項目定義的參照
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"$ref": "#definitions/MyObjectList"
}
...
"definitions": {
"MyObjectList": {
"type": "array",
"items": {
"$ref": "#definitions/MyObject"
}
}
"MyObject": {
"type": "object",
"properties": {...}
}
}
}在 Apex 與 Flow Builder 中,宣告 myObjects 參數和 Apex 元素類型 ExternalService__RegistrationName_MyObject 的集合變數。
可參照的陣列定義與內嵌陣列項目定義
{
"swagger": "2.0",
...
"name": "myObjects",
"in": "body",
"schema": {
"$ref": "#definitions/MyObjectList"
}
...
"definitions": {
"MyObjectList": {
"type": "array",
"items": {
"type": "object",
"properties": {...}
}
}
}
}在 Apex 與 Flow Builder 中,宣告 myObjects 參數和 Apex 元素類型 ExternalService__RegistrationName_MyObjectList 的集合變數。
此文章是否解決您的問題？
請讓我們知道，以便我們改進！
