1. 前言

安裝使用node.js SDK可以幫助開發者快速接入使用天翼云的日志服務相關功能，目前支持同步上傳功能。

2. 使用條件

2.1. 先決條件

用戶需要具備以下條件才能夠使用LTS SDK node.js版本：

1、購買并訂閱了天翼云的云日志服務，并創建了日志項目和日志單元，獲取到相應編碼（logProject、logUnit）。

2、已獲取AccessKey 和 SecretKey。

3、已安裝node.js運行環境,推薦node16以上環境。

2.2. 下載及安裝

從官方渠道下載ctyun_lts_nodejs_sdk.zip壓縮包，放到相應位置后并解壓。“ctyun_lts_nodejs_sdk/src”目錄中index.ts為SDK的使用示例代碼。

2.2.1. 編譯使用

1、node,js sdk 使用前需安裝node.js運行環境。

2、打開項目，執行以下命令安裝依賴。如果失敗，可以加上鏡像源，比如天翼云：npm install --registry=xxx

npm install

3、安裝ts-node，ts-node是用于編譯并執行TypeScript文件的工具。

npm  i ts-node -g

4、將ts文件編譯為js文件。它會將js文件輸出到dist目錄下。（可在tsconfig.json里面進行修改）

tsc

5、運行測試用例。

ts-node ./src/index.js

3. SDK使用設置

3.1. 基本使用

使用 SDK訪問云日志服務，需要設置正確的 AccessKey、SecretKey 和endpoint，所有的服務可以使用同一 key 憑證來進行訪問，但不同的服務地區需要使用不同的 endpoint 進行訪問，詳情參考天翼云官網-SDK接入概述。在調用前SDK，需要已知以下參數：

• 云日志服務訪問地址。詳情請查看訪問地址（Endpoint）。
• key憑證：accessKey和secretKey 。詳情請查看如何獲取訪問密鑰（AK/SK）。
• 日志項目編碼：logProject，在使用SDK前，需要確保您有至少一個已經存在的日志項目。
• 日志單元編碼：logUnit，在使用SDK前，需要確保日志項目中有至少一個已經存在的日志單元。
• 待上傳的日志：logItem，在使用SDK前，需要確保日志已按照特定格式組織。

參數	參數類型	描述	是否必須
endpoint	string	域名	是
accessKey	string	AccessKey，簡稱ak	是
secretKey	string	SecretKey ，簡稱sk	是
logProject	string	日志項目編碼	是
logUnit	string	日志單元編碼	是

示例代碼：SDK使用示例

import Client from './client'
import LogItem from './logItem'
 ? 
async function testPutlog() {
 ?  const ak = 'your accessKey'
 ?  const sk = 'your secretKey'
 ?  const logProject = 'your logProject' ? //日志項目編碼
 ?  const logUnit = 'your logUnit' ? ? ? ? //日志單元編碼
 ?  const endpoint = 'your endpoint' ? ? ? //不同資源池endpoint不同,請參考文檔 ?

 ?  const logItems = new Array();
 ?  for (let i = 0; i < 10; i++) {  //一次請求上傳10條日志
 ? ? ?  const logItem =  new LogItem('node.js sdk test');
 ? ? ?  logItem.setLogTimestamp(Date.now()*1000*1000) ? //可省略,默認為當前時間
 ? ? ?  logItem.addContent('contentString', 'contents test string')  //增加分詞內容,也可不加
 ? ? ?  logItem.addContent('contentDouble', 3.1415926)  //增加分詞內容,也可不加
 ? ? ?  logItems.push(logItem)
 ?  }
 ?  try {
 ? ? ?  const client = new Client(ak,sk,endpoint)
 ? ? ?  //初始化更新一次token,后續自動更新
 ? ? ?  await client.getToken() ? ? ? ?

 ? ? ?  //上傳日志，100次，總計100*10 = 1000條日志
 ? ? ?  for (let i = 0; i < 100; i++) {
 ? ? ? ? ?  const res = await client.putLogs(logProject, logUnit, logItems)
 ? ? ? ? ?  console.log('statusCode:',logResponse.statusCode,', message:',logResponse.message,', error:',logResponse.error);

 ? ? ?  }
 ?  } catch (e) {
 ? ? ?  console.log(e)
 ?  }

}

//執行測試
testPutlog()

4. LTS服務代碼示例

4.1. 關于Client的操作

4.1.1. Client()

此操作是初始化client，client包含的配置信息如下：

參數	參數類型	描述	是否必須
endpoint	string	域名	是
accessKey	string	AccessKey，簡稱ak	是
secretKey	string	SecretKey ，簡稱sk	是
compressType	string	日志壓縮方式 ，默認lz4	否
securityToken	ITokenInfo	token信息	否
httpClient	HttpClient	用于http請求	否

示例代碼：初始化創建Client

const client = new Client(ak,sk,endpoint)

4.1.2. getToken()

此操作是為client注入token信息，這一步需要使用ak和sk信息換取臨時憑證TokenInfo，其中包含了token隨機串和過期時間兩個參數。這一步需要去訪問CTIAM的api接口，調用api接口，返回token信息。

TokenInfo信息如下：

參數	類型	描述
token	string	token 隨機串
expireTime	number	過期時間，默認30分鐘

示例代碼：初始化Token

 await client.getToken() ? ? ? ?

4.2. 關于Log的操作

4.2.1. logItem()

此操作用于生成待上傳的日志，其中LogItem格式如下，日志上傳默認只支持Array,如果只上傳一條也需要加入到Array中。

參數	類型	描述	是否必須
logTimestamp	number	時間戳，單位納秒	是
originMsg	string	原始日志內容	是
contents	Map<string, any>	kv類型，日志分詞，可用于索引	否
labels	Map<string, any>	kv類型，自定義label	否

注意：其中Contents和Labels的key的長度不超過64字符，僅支持數字、字母、下劃線、連字符(-)、點(.),且必須以字母開頭。value類型最好使用字符串（string）和數字類型（number），其他類型建議先轉為字符串類型，并且value值不能為空或空字符串。

示例代碼：組裝生成10條日志

const logItems = new Array();
for (let i = 0; i < 10; i++) { ?
 ?  const logItem =  new LogItem('node.js sdk test');
 ?  logItem.setLogTimestamp(Date.now()*1000*1000) ? //省略,則默認為當前時間
 ?  logItem.addContent('contentString', 'contents test string')  //分詞內容,可不加
 ?  logItem.addContent('contentDouble', 3.1415926) ? 
 ?  logItem.addLabel('labelString','tag') ? ? 
 ?  logItems.push(logItem)
}

//常用方式
 const logItems = new Array();
for (let i = 0; i < 10; i++) { ?
 ?  const logItem =  new LogItem('node.js sdk test');
 ?  logItems.push(logItem)
}

4.3. 關于日志上傳的操作

4.3.1. putLogs()

此操作用于日志上傳服務，需要傳入的參數有三個，分別是logProject(日志項目編碼)，logUnit(日志單元編碼)，logItems（要上傳的日志）。

參數	類型	描述	是否必須
logProject	string	日志項目編碼	是
logUnit	string	日志單元編碼	是
logItems	Array	日志信息	是

示例代碼：上傳日志

const logResponse = await client.putLogs(logProject, logUnit, logItems)
console.log("res:",logResponse)

4.3.2. logResponse

logResponse 是putlogs方法的返回響應體，如下表格式：

參數	類型	描述	示例
statusCode	string	返回碼，取值范圍：0：-正常、-1：嚴重錯誤,其他自定義
message	string	狀態描述	SUCCESS
error	string	參考錯誤編碼列表

示例代碼：獲取返回結果

logResponse.statusCode
logResponse.message
logResponse.error

日志服務相關錯誤編碼(部分):

statusCode	error	message
-1	LTS_8000	請求失敗，請稍候重試，或提交工單反饋
-1	LTS_8001	內容不合法，無法解析
-1	LTS_8004	日志內容包含的日志必須小于[x] MB和[y]條
-1	LTS_8006	日志內容解壓失敗
-1	LTS_8007	Token失效，請重新獲取
-1	LTS_8009	無云日志服務產品實例，請先開通云日志服務
-1	LTS_8010	日志項目不存在
-1	LTS_8011	日志單元不存在
-1	LTS_8013	在1個日志項目下,寫入流量最大限制:200MB/s
-1	LTS_8014	在1個日志項目下,寫入次數最大限制:1000次/s
-1	LTS_8015	在1個日志單元下,寫入流量最大限制:100MB/s
-1	LTS_8016	在1個日志單元下,寫入次數最大限制:500次/s
-1	LTS_18000	調用ITIAM的接口失敗