Darabonba 是阿里雲致力於更好的描述 OpenAPI 而開發的特定領域編程語言,不僅可以兼容多網關描述任意風格的 OpenAPI,並且可通過編寫 Darabonba 的文件自動化生成多語言的 SDK,是節省開發成本的不二之選。由於 Darabonba 具備編程的靈活性,所以不僅能為 OpenAPI 生成 SDK ,同時還可以通過 Darabonba 編寫關於 SDK 中OpenAPI 使用的場景化 CodeSample,為 SDK 的使用者提供了最為實用的指導。本篇文章將通過三個示例,逐步幫助大家生成屬於自己的 CodeSample。
Hello,World
首先,我們可以點擊本次 Code Sample 全民賽碼 挑戰賽的主頁面,點擊下面的<快速開始>:
此頁面需要使用阿里雲賬號登錄,在登陸成功後即可跳轉到 CodeSample 項目創建頁面,這裡只需要填寫本次 CodeSample 的項目標題和描述即可,其他的信息已經填寫好了包括之後需要用的 Console 模塊,在依賴庫中也幫大家默認填寫了,所以在輸入了標題後描述後直接點擊下一步:
在第二步的頁面中,可以看到下面編輯框中已經為大家準備好了一段可以生成各語言的初始代碼,大家可以通過修改字符串並點擊編輯框下方的查看生成代碼來感受通過 Darabonba 生成的各語言代碼,最後可以通過提交來保存這段代碼:
在保存成功後,會跳轉到<我的示例>列表頁面中,通過點擊下面的詳情按鈕,直接進入這個 CodeSample 項目的詳情頁面:
在詳情頁面中,我們可以通過編輯按鈕,再次編輯我們之前用 Darabonba 編寫的 Hello,World 文檔,在編輯完成併成功保存後,就可以點擊發布新版本的按鈕將寫好的 CodeSample 代碼提交到 CodeSample 全民賽碼 參加評比了(評委會以每個項目的最後一次提交代碼為準)。
使用單個API的CodeSample
當然,如果只是提交 Hello,World 文檔是不能獲得大賽獎品的,Darabonba 的 CodeSample 代碼是為OpenAPI SDK 服務的,所以我們下面將通過為一個 OpenAPI 寫CodeSample來為大家描寫一個示例。
首先需要再新建一個API的項目,這裡我們在依賴庫中會加入我們將要編寫 CodeSample 所對應的 SDK 模塊,相關模塊可以直接點擊右側邊欄中的<模塊倉庫>,通過倉庫可以尋找到雲產品的 SDK 模塊:
我們選取阿里雲的短信服務的 SDK 模塊alibabacloud:
Dysmsapi20170525
來編寫其對應的CodeSample,首先我們進入模塊的詳情頁面;在詳情頁面中,我們可以看到這個SDK 相關的一些跟 OpenAPI 請求相關的方法和定義了入參、出參的 Model。這裡我們選取最為經典發送短信的SendSms
方法來編寫相關 CodeSample ,並可以點擊其對應的入參類型 SendSmsRequest
和出參類型 SendSmsResponse
來了解其如何使用,其中在入參中標記紅星的為必選參數。
在對這個方法有一定的瞭解以後我們就接著來創建我們的項目,這次跟上次最大的區別就是:在依賴庫中我們需要填入Dysmsapi20170525
相關的依賴。
而在下一步中,我們就可以在代碼中使用到 SDK 相關的模塊編寫其 CodeSample了:
import Dysmsapi;
import RPC;
import Console;
// 使用AK&SK初始化賬號Client
static function createClient (accessKeyId : string , accessKeySecret : string , regionId : string) : Dysmsapi{
var config = new RPC.Config{};
config.accessKeyId = accessKeyId;
config.accessKeySecret = accessKeySecret;
config.regionId = regionId;
}
static async function main(args: [string]): void {
var client = createClient("accessKeyId","accessKeySecret","regionId");
var request = new Dysmsapi.SendSmsRequest{
phoneNumbers= "13888888888",
// 短信簽名名稱。請在控制檯簽名管理頁面簽名名稱一列查看。
signName= "aliyun",
// 短信模板ID。請在控制檯模板管理頁面模板CODE一列查看。
templateCode = "SMS_153055065",
};
var response = client.sendSms(request);
Console.log(response.message);
}
通過查看生成代碼,確定生成無誤以後,我們就可以保存該 CodeSample 並通過上文提到過的方法,在詳情頁面中直接點擊發布新版本提交該 CodeSample 了。
完整的場景化示例
在瞭解瞭如何通過 Darabonba 的生態來編程實現多語言 CodeSample 以後,接下來我們就來做一件有挑戰的事情,就是通過組合多個 API 形成一個場景,這裡我們以阿里雲容器服務的 OpenAPI 為例實現一個,從 創建集群->查看集群狀態->擴容集群->查看集群節點狀態->刪除節點的示例。
首先還是新建一個項目,在依賴項中這次我們要用到倉庫中容器服務相關的 SDK 模塊:
通過引入對應的模塊,我們就可以通過使用這些模塊中對應的方法來實現上述的流程了,再加上相應的註釋,一個完成的 CodeSample 示例就完成了,代碼如下:
import CS;
import ROA;
import Util;
import Console;
/**
* 使用AK&SK初始化賬號Client
* @param accessKeyId
* @param accessKeySecret
* @param regionId
* @param endpoint
* @return Client
* @throws Exception
*/
static async function createClient (accessKeyId : string , accessKeySecret : string , regionId : string)throws : CS{
var config = new ROA.Config{};
// 您的AccessKey ID
config.accessKeyId = accessKeyId;
// 您的AccessKey Secret
config.accessKeySecret = accessKeySecret;
// 您的可用區ID
config.regionId = regionId;
return new CS(config);
}
/**
* 創建集群
* @param client
* @return CreateClusterResponse
* @throws Exception
*/
static async function createCluster (client: CS)throws : CS.CreateClusterResponse{
var createClusterRequestBody = new CS.CreateClusterBody{
// 失敗是否回滾
disableRollback=true,
// 集群名稱
name="my-test-Kubernetes-cluster",
// 集群創建超時時間
timeoutMins=60,
// 集群類型,ManagedKubernetes
clusterType="ManagedKubernetes",
// 地域
regionId="cn-beijing",
// VPC ID
vpcid="vpc-2zegvl5etah5requ0****",
// 容器POD CIDR
containerCidr="172.20.0.0/16",
// 服務CIDR
serviceCidr="172.21.0.0/20",
// 是否開放公網SSH登錄
sshFlags=false,
// 是否安裝雲監控插件
cloudMonitorFlags=false,
// 節點SSH登錄密碼,和key_pair二選一
loginPassword="Test_1234",
// Worker節點付費類型PrePaid|PostPaid
workerInstanceChargeType="PostPaid",
// Worker實例規格多實例規格參數
workerInstanceTypes=["ecs.sn2.3xlarge"],
// 一臺或多臺虛擬交換機 ID,N 的取值範圍為 [1, 5]
workerVswitchIds=["vsw-2ze48rkq464rsdts****"],
// Worker系統盤類型
workerSystemDiskCategory="cloud_efficiency",
// Worker節點系統盤大小
workerSystemDiskSize=120,
// Worker節點數
numOfNodes=3,
// 是否配置SNATEntry
snatEntry=true,
// 是否公網暴露集群endpoint
endpointPublicAccess=false,
// 節點端口範圍,默認30000-65535
nodePortRange="30000-32767",
// 網絡模式, 可選值iptables|ipvs
proxyMode="iptables",
// 是否開啟集群刪除保護,防止通過控制檯或api誤刪除集群
deletionProtection=true,
// 運行pod的主機的操作系統類型,例如:linux,Windows等
osType="linux",
};
var createClusterReq = new CS.CreateClusterRequest{
body=createClusterRequestBody
};
return client.createCluster(createClusterReq);
}
/**
* 查詢集群狀態
* @param client
* @param clusterId
* @return DescribeClusterDetailResponse
* @throws Exception
*/
static async function describeClusterDetail (client: CS, clusterId: string)throws : CS.DescribeClusterDetailResponse{
var describeClusterDetailReq = new CS.DescribeClusterDetailRequest{};
return client.describeClusterDetail(clusterId,describeClusterDetailReq);
}
/**
* 擴容
* @param client
* @param clusterId
* @return ScaleOutClusterResponse
* @throws Exception
*/
static async function scaleOutCluster (client: CS, clusterId: string) throws : CS.ScaleOutClusterResponse{
var scaleOutClusterRequestBody = new CS.ScaleOutClusterBody{
// keypair名稱,和login_password 二選一
keyPair="common",
// 一臺或多臺虛擬交換機 ID,N 的取值範圍為 [1, 3]
vswitchIds=["vsw-uf684tfrpwup8gcsw****"],
// Worker實例規格多實例規格參數
workerInstanceTypes=["ecs.c5.xlarge"],
// Worker系統盤類型
workerSystemDiskCategory="cloud_efficiency",
// Worker節點系統盤大小
workerSystemDiskSize=120,
// 是否掛載數據盤 true|false
workerDataDisk=false,
// 擴容的數量
count=10,
};
var scaleOutClusterReq = new CS.ScaleOutClusterRequest{
body=scaleOutClusterRequestBody
};
return client.scaleOutCluster(clusterId,scaleOutClusterReq);
}
/**
* 查詢節點,子賬號AK訪問會報權限錯誤
* @param client
* @param clusterId
* @return DescribeClusterNodesResponse
* @throws Exception
*/
static async function describeClusterNodes (client: CS, clusterId: string) throws : CS.DescribeClusterNodesResponse{
var describeClusterNodesRequestQuery = new CS.DescribeClusterNodesQuery{
// 可選 每頁顯示條數
pageSize="18",
// 可選 頁碼數
pageNumber="1",
// 可選 nodepool_id
nodepoolId="nodepool_id",
// 狀態
state="running",
};
var describeClusterNodesReq = new CS.DescribeClusterNodesRequest{
query=describeClusterNodesRequestQuery
};
return client.describeClusterNodes(clusterId,describeClusterNodesReq);
}
/**
* 移除節點
* @param client
* @param clusterId
* @return DeleteClusterNodesResponse
* @throws Exception
*/
static async function deleteClusterNodes (client: CS, clusterId: string, instanceId: string) throws : CS.DeleteClusterNodesResponse{
var deleteClusterNodesBody = new CS.DeleteClusterNodesBody{
//要移除的node_name數組
nodes=[ instanceId ],
//是否同時釋放ecs節點
releaseNode="false"
};
var deleteClusterNodesReq = new CS.DeleteClusterNodesRequest{
body=deleteClusterNodesBody
};
return client.deleteClusterNodes(clusterId, deleteClusterNodesReq);
}
static async function main(args: [string]): void {
// 1. 初始化客戶端
var client = createClient("accessKeyId","accessKeySecret","regionId");
// 2. 創建集群
var createClusterRes = createCluster(client);
var clusterId = createClusterRes.body.clusterId;
// 3. 查詢集群狀態
var describeClusterDetailRes = describeClusterDetail(client, clusterId);
// 4. 當集群狀態為“running” 時 進行擴容
if(Util.equalString(describeClusterDetailRes.body.state, "running")) {
var scaleClusterRes = scaleOutCluster(client, clusterId);
Console.log(scaleClusterRes.body.requestId);
}
// 5. 查詢節點
var describeClusterNodesRes = describeClusterNodes(client, clusterId);
var describeClusterNodesResHeaders = describeClusterNodesRes.headers;
var node = describeClusterNodesRes.body.nodes[0];
var instanceId = node.instanceId;
// 6. 移除節點
var deleteClusterNodesRes = deleteClusterNodes(client, clusterId, instanceId);
Console.log(deleteClusterNodesRes.body.requestId);
}