1. 前言

安裝(zhuang)使用.NET SDK可(ke)以幫(bang)助開發者快(kuai)速接入使用天(tian)翼(yi)云的日志服(fu)務相關功能，目(mu)前支(zhi)持同步上傳功能。

2. 使用條件

2.1. 先決條件

用戶需要具備以下條件才能(neng)夠使(shi)用LTS SDK .net版本(ben)：

1、購(gou)買并訂閱(yue)了天(tian)翼(yi)云的云日(ri)志服務，并創建了日(ri)志項(xiang)目和日(ri)志單元，獲(huo)取到(dao)相(xiang)應(ying)編碼（logProject、logUnit）。

2、已獲取(qu)AccessKey 和 SecretKey。

3、已安裝C#10.0 以上開(kai)發環(huan)境，推(tui)薦支持.NET 6或以上版(ban)本。

2.2. 下載及安裝

項目基于(yu)(yu).Net Standard 2.0 構建(jian)，可(ke)適(shi)用于(yu)(yu).netcore、.net5.0以上框架使用。從官方渠道下載ctyun_lts_net_sdk.zip壓縮包(bao)，放到相應位置后(hou)并解壓。“ctyun_lts_net_sdk”目錄(lu)中ctyun_lst_net_sdk 模塊(kuai)是SDK的邏輯代碼，test_net_sdk模塊(kuai)為SDK的使用示例代碼。

1、執行以下命(ming)令構(gou)(gou)建(jian)項目(mu)，這將在bin/Debug目(mu)錄下生成對(dui)應文(wen)件(jian)。如果使用的是IDE，則(ze)根(gen)據工(gong)具的特性，自(zi)行構(gou)(gou)建(jian)。

dotnet build 

2、在test_net_sdk 模塊（或您自定義的(de)模塊）中的(de)test_net_sdk.csproj里面添(tian)加上對(dui)net sdk 的(de)項目依(yi)賴ItemGroup。

<Project Sdk="Microsoft.NET.Sdk">

 ?  <PropertyGroup>
 ? ? ?  <TargetFramework>net6.0</TargetFramework>
 ? ? ?  <OutputType>Exe</OutputType>
 ? ? ?  <ImplicitUsings>enable</ImplicitUsings>
 ? ? ?  <Nullable>enable</Nullable>
 ?  </PropertyGroup>
 ?  <ItemGroup>
 ? ? ?  <ProjectReference Include="..\ctyun_lts_net_sdk\ctyun_lts_net_sdk.csproj" />
 ?  </ItemGroup>
</Project>

3、如果本(ben)地安裝的.net 版(ban)本(ben)發生變動，請修改test_net_sdk.csproj文(wen)件中的TargetFramework 為對應版(ban)本(ben)

 <PropertyGroup>
 ? ? ?  <OutputType>Exe</OutputType>
 ? ? ?  <TargetFramework>net6.0</TargetFramework> ?  <!--需匹配已安裝的net版本-->
 ? ? ?  <ImplicitUsings>enable</ImplicitUsings>
 ? ? ?  <Nullable>enable</Nullable>
 ? ? ? .....
 </PropertyGroup>

3. SDK基本使用

3.1. 基本使用

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

• 云日志服務訪問地址。詳情請查看訪問地址（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	日志單元編碼	是

示例代碼(ma)：SDK日志上傳

using Ctyun.LTS.LOG.Data;
using Ctyun.LTS.LOG.Response;

namespace Ctyun.LTS.LOG.Example
{
 ?  class SamplePutLogs
 ?  {
 ? ? ?  public static void Main()
 ? ? ?  {
 ? ? ? ? ?  string endpoint = "your endpoint";
 ? ? ? ? ?  string accessKey = "your accessKey";
 ? ? ? ? ?  string secretKey = "your secretKey";
 ? ? ? ? ?  string logProject = "your logProject";
 ? ? ? ? ?  string logUnit = "your logUnit";

 ? ? ? ? ?  // logItems include 10 logItem
 List<LogItem> logItems = new List<LogItem>();
 ? ? ? ? ?  for (int i = 1; i <= 10; ++i) {
 ? ? ? ? ? ? ?  LogItem logItem = new LogItem();
 ? ? ? ? ? ? ?  logItem.OriMsg = ".NET SDK";
 ? ? ? ? ? ? ?  logItem.PushBackContents("error_string", "invalid operation");
 ? ? ? ? ? ? ?  logItem.PushBackContents("content.Int", 12345);
 ? ? ? ? ? ? ?  logItem.PushBackContents("content_double", 3.1415926);
 ? ? ? ? ? ? ?  logItem.PushBackLabels("user_tag", "string");
 ? ? ? ? ? ? ?  logItems.Add(logItem);
 ? ? ? ? ?  }
 ? ? ? ? ?  try
 ? ? ? ? ?  {
 ? ? ? ? ? ? ?  LogClient client = new LogClient(endpoint, accessKey, secretKey);
 ? ? ? ? ? ? ?  for (int i = 0; i < 100; i++) ?  //send 100 times
 ? ? ? ? ? ? ?  {
 ? ? ? ? ? ? ? ? ?  PutLogsResponse response = client.PutLogs(logProject, logUnit, logItems);
 ? ? ? ? ? ? ? ? ?  response.Print();
 ? ? ? ? ? ? ?  }
 ? ? ? ? ?  }
 ? ? ? ? ?  catch (LogException le)
 ? ? ? ? ?  {
 ? ? ? ? ? ? ?  le.Print();
 ? ? ? ? ?  }
 ? ? ? ? ?  catch (Exception e)
 ? ? ? ? ?  {
 ? ? ? ? ? ? ?  Console.WriteLine(e);
 ? ? ? ? ?  }
 ? ? ?  }
 ? ? }

4. LTS服務代碼示例

4.1. 關于Client的操作

4.1.1. new LogClient()

此操作是初始化Client。Client配(pei)置如下：

參數	參數類型	描述	是否必須
endpoint	string	域名，詳情參考天翼云官網	是
accessKey	string	AccessKey，簡稱ak	是
secretKey	string	SecretKey ，簡稱sk	是
securityToken	TokenInfo	token臨時憑證和過期時間	否
clientConfig	ClientConfig	httpclient的配置	否
serviceClient	ServiceClient	httpclient發送http請求	否

示例代碼(ma)：初始化Client

LogClient client = new LogClient(endpoint, accessKey, secretKey);

4.2. 關于臨時憑證Token的操作

4.2.1. RefreshToken()

此操作是為client注入token信(xin)息，這(zhe)一(yi)步需要(yao)使(shi)用(yong)ak和sk信(xin)息換取(qu)臨時憑證TokenInfo，其(qi)中包含了token隨機串和過(guo)期時間(jian)兩(liang)個參(can)數。這(zhe)一(yi)步需要(yao)去訪問CTIAM的api接口(kou)，調用(yong)api接口(kou)，傳入ak/sk/endpoint信(xin)息，返回(hui)token信(xin)息。

TokenInfo信息如(ru)下：

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

獲(huo)取(qu)TokenInfo這(zhe)(zhe)一步(bu)在Client 初始化時會自動(dong)調用(yong)(yong)RefreshToToken，用(yong)(yong)戶(hu)默認可以不用(yong)(yong)進行這(zhe)(zhe)一步(bu)操作。同時在token過期前5分鐘會再次去(qu)獲(huo)取(qu)token。

示例代碼：使用ak,sk去獲取臨時憑(ping)證(zheng)token

RefreshToken();

4.3. 關于Log的操作

4.3.1. new logItem()

此操作用于生成待上傳的日志，日志同步上傳只能上傳List格式的(de)日志，logItems是一個List類型，里面包(bao)含若(ruo)干條(tiao)LogItem日志，LogItem格式如下：

參數	類型	描述	是否必須
timestamp	Int64	時間戳，單位納秒	是
OriMsg	string	原始日志內容	是
contents	Dictionary<string, object>	日志內容，分詞后的內容，可用于索引	否
labels	Dictionary<string, object>	自定義標簽	否

new LogItem()時會自動設置(zhi)一(yi)個當前的(de)時間戳，如果希望自定義時間戳，可(ke)以主動賦(fu)值。

示例代碼(ma)：組裝生(sheng)成10條日(ri)志

List<LogItem> logItems = new List<LogItem>();
for (int i = 1; i <= 10; ++i) {
 ? ? LogItem logItem = new LogItem();
 ? ? logItem.OriMsg = ".NET SDK";
 ? ? logItem.PushBackContents("error_string", "invalid operation");
 ? ? logItem.PushBackContents("content_Int", 12345);
 ? ? logItem.PushBackContents("content_double", 3.1415926);
 ? ? logItem.PushBackLabels("user_tag", "string");
 ? ? logItems.Add(logItem);
}

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

4.4. 關于日志上傳的操作

4.4.1. PutLogs()

此操(cao)作用(yong)于日(ri)志(zhi)上傳(chuan)(chuan)服務，需要傳(chuan)(chuan)入(ru)的(de)參(can)數有(you)三個，分別是(shi)logProject(日(ri)志(zhi)項目編(bian)碼)，logUnit(日(ri)志(zhi)單元(yuan)編(bian)碼)，logItems（要上傳(chuan)(chuan)的(de)日(ri)志(zhi)）。

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

示例代碼(ma)：上傳日志,默(mo)認使用lz4壓縮

PutLogsResponse response = client.PutLogs(logProject, logUnit, logItems);

response 是Response格式的返回響應體(ti)，如下表格式：

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

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

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的接口失敗