關於使用 SDK 開發自訂元件
技能中的每個狀態都使用系統元件或自訂元件。
系統元件內建於技能，且永遠可用。它們提供動作，例如輸出文字和設定變數。自訂元件提供商業系統 (例如資料庫和 CRM 系統) 的存取權。
To develop a complete custom component, you create an API in Oracle Mobile Hub and define its endpoints along with a backend, which controls access to the API.After the API and backend are defined, you create a connector in Oracle Mobile Hub.連線器的目的是將連線詳細資訊摘要至記錄系統，而不需要在實行中編碼連線詳細資訊。Finally, you write the API’s implementation and upload it to Oracle Mobile Hub.
建立自訂元件
定義 API 端點
若要定義自訂元件的端點：
- In the side menu, expand Development and click APIs.
- Click New API and select API.
- Enter a name and a short description for the API and click Create.
- When the API page opens, click Endpoints.
- Click New Resource.
- In the Resource Path field, enter components then click Methods.
- Click Add Method and select GET.
- When the page for the components endpoint opens, click Save.
- Go back to the Endpoints page and click the plus sign beside the components resource.A nested resource is added.
- In the Resource Path field for the new resource, enter {componentName} then click Methods.
- Select Required then click Add Method and select POST.
- Click Save.
Next, click Security and make sure that the Login Required switch is off.
建立並設定後端
後端的作用就像是機器人與其自訂元件之間的安全閘道，會以一或多個 Api 的方式實行。
建立後端之後，您需要將一或多個 Api 與其關聯。您可以透過後端存取關聯的 API，以提供 API 和處理認證的基礎 URL。
- In the side menu, expand Development and click Backends.
- Click New Backend.
- Enter a name and a description for the backend and click Create.
- After the backend is created, associate an API to the backend.
建立連線器
在您開始之前，請收集下列資訊：
-
描述您所連線 API 的 Swagger 文件。如果您沒有 Swagger 文件，那麼您需要 API 的基本 URL。
-
您所連線之 API 的安全證明資料。連線器支援 OAUTH、基本認證、SAML 以及 JWT。
建立連線器：
- In the side menu, expand Development and click Connectors.
- Click New Connector and select REST.
- Enter a name and a description for the connector and click Create.The configurator opens to the General page.
- Click Descriptor and enter the location of the Swagger document.If you don't have a Swagger document, select I don't have a descriptor and enter the base URL of the API.
- Click Security and set the security policies for the connector.
- Click Test and test the connection to make sure that the connector is working.For example, if you are connecting to a database, make sure that you can send an SQL statement and get the result.
- When you are done testing, click Done.
撰寫自訂元件的實行代碼
定義 API 端點並設定後端之後，您就可以開發自訂元件的實行。
下列範例顯示自訂元件的內部結構，它為技能機器人提供訂單編號服務，而技能機器人則為銷售市場的公司提供線上訂單。
tshirtordertaker
\---tshirtordertaker
| package-lock.json
| package.json
| tshirtordertaker.js
|
+---components
| OrderNumber.js
|
+---lib
| config.js
| database.js
此範例顯示檔案結構的建議版面配置。The main field in package.json points to tshirtordertaker.js.Within tshirtordertaker.js, you initialize the component middleware, where you define the location of the file or files that implement the custom component.
The following sample shows what thsirtordertaker.js looks like.The location of the custom component implementation is defined in the register option, which in this case is the ./components directory.
/**
* The ExpressJS namespace.
* @external ExpressApplicationObject
* @see {@link http://expressjs.com/3x/api.html#app}
*/
const OracleBot = require('@oracle/bots-node-sdk');
/**
* Mobile Cloud custom code service entry point.
* @param {external:ExpressApplicationObject} service
*/
module.exports = function(service) {
OracleBot.init(service, {
logger: console
});
OracleBot.Middleware.customComponent(service, {
cwd: __dirname,
baseUrl: '/mobile/custom/TShirtOrderTaker/components',
register: './components',
});
};
The baseUrl value is in the form of /mobile/custom/<API-Name>/components where <API-Name> is the name that you gave the API when you created it in Oracle Mobile Hub.The register value is the directory that contains the file or files that implement the service.
In this case, the components directory has one file, called OrderNumber.js.This file contains the metadata and invoke functions that the bot system requires of every custom component.The following snippet shows what the beginning of OrderNumber.js looks like:
'use strict'
const { DBConnector } = require('../lib/database');
const { DB_CONNECTOR_NAME, DB_CONNECTOR_VERSION } = require('../lib/config');
/**
* normalize color for db queries
* @param {string} color
*/
module.exports = {
metadata: () => ({
name: "OrderNumber",
properties: { customerID: { type: "string", required: true } },
supportedActions: [
"instock",
"backorder"
]
}),
invoke: (conversation, done) => {
// deconstruct the conversation to get connectors instance
const { oracleMobile } = conversation;
if (!oracleMobile) {
conversation.error(true);
conversation.reply('The oracleMobile reference was not found. There might be a problem with this API');
done();
} else {
// instantiate DBConnector helper class with backend connectors object
const db = new DBConnector(oracleMobile.connectors, DB_CONNECTOR_NAME, DB_CONNECTOR_VERSION);
.
.
.
In this case, a connection to a database is made through a connector API in Oracle Mobile Hub.In the example structure shown earlier, the code for DBConnector would be implemented in database.js.您自己的導入程式碼將會不同，但結構應該相同。
上傳實行
您上傳的套裝程式稱為實行存檔，且包含在.zip 檔案中。
這裡所述上傳實行的處理作業是手動處理作業。不過，命令行選項是可用的。See the Oracle Mobile Hub documentation for instructions on how to download, set up, and use the Custom Code Test Tools that are on Oracle Technology Network (OTN).
- Zip the top-level directory to create an implementation archive.
- Upload the package to your API.
- Log into Oracle Mobile Hub and open your API.
- On the API page, click Implementation.
- Upload the API.You can click Upload an implementation archive or drag it onto the page.
測試實行
上傳實行之後，您應該進行測試。
- Click Test at the top of the page.
- Make sure that the GET /components endpoint is selected
- Select the appropriate Backend.
- Set the Authentication Method.
- Click Test Endpoint.
如果測試成功，您應該會見到 200 的回應狀態和 JSON 有效負載。有效負載應具有與下列 JSON 相同的結構：
{
"version": "1.1",
"components": [
{
"name": "OrderNumber",
"properties": {
"customerID": {
"type": "string",
"required": true
}
},
"supportedActions": [
"instock",
"backorder"
]
}
]
}新增自訂元件至您的 Bot
在部署自訂元件並準備好進行作業之後，將其新增至技能機器人。
您必須先在技能機器人 UI 中設定元件服務，以新增自訂元件。接下來，您可以編輯 BotML 流程，以新增呼叫自訂元件的狀態以及處理回應的狀態。設定好所有項目之後，請測試機器人。
建立自訂元件的服務
若要設定服務，您需要提供代管自訂元件之服務的連線和認證資訊。
您需要代管自訂元件 API 的後端 ID，以及行動使用者的匿名金鑰或證明資料。您可以從建立的後端摘要頁面取得後端 ID 和匿名索引鍵，以代管 API。
您還需要服務用來擷取自訂元件之描述資料的 URL。You can form the metadata URL by copying the URL for the API from the General page of the API Designer and then appending /components to it.
- In the designer UI for your skill bot, open the components editor.
- Click + Service.
- Enter the connection and authentication information for the service that hosts your custom component.If you're using an Oracle Mobile Hub backend, make sure that you append the Metadata URL with
/components. - Click Create.