1. 前言

安装使用.NET SDK可以帮助开发者快速接入使用天翼云的日志服务相关功能，目前支持同步上传功能。

2. 使用条件

2.1. 先决条件

用户需要具备以下条件才能够使用LTS SDK .net版本：

1、购买并订阅了天翼云的云日志服务，并创建了日志项目和日志单元，获取到相应编码（logProject、logUnit）。

2、已获取AccessKey 和 SecretKey。

3、已安装C#10.0 以上开发环境，推荐支持.NET 6或以上版本。

2.2. 下载及安装

项目基于.Net Standard 2.0 构建，可适用于.netcore、.net5.0以上框架使用。从官方渠道下载ctyun_lts_net_sdk.zip压缩包，放到相应位置后并解压。“ctyun_lts_net_sdk”目录中ctyun_lst_net_sdk 模块是SDK的逻辑代码，test_net_sdk模块为SDK的使用示例代码。

1、执行以下命令构建项目，这将在bin/Debug目录下生成对应文件。如果使用的是IDE，则根据工具的特性，自行构建。

dotnet build 

2、在test_net_sdk 模块（或您自定义的模块）中的test_net_sdk.csproj里面添加上对net sdk 的项目依赖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、如果本地安装的.net 版本发生变动，请修改test_net_sdk.csproj文件中的TargetFramework 为对应版本

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

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日志上传

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配置如下：

参数	参数类型	描述	是否必须
endpoint	string	域名，详情参考天翼云官网	是
accessKey	string	AccessKey，简称ak	是
secretKey	string	SecretKey ，简称sk	是
securityToken	TokenInfo	token临时凭证和过期时间	否
clientConfig	ClientConfig	httpclient的配置	否
serviceClient	ServiceClient	httpclient发送http请求	否

示例代码：初始化Client

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

4.2. 关于临时凭证Token的操作

4.2.1. RefreshToken()

此操作是为client注入token信息，这一步需要使用ak和sk信息换取临时凭证TokenInfo，其中包含了token随机串和过期时间两个参数。这一步需要去访问CTIAM的api接口，调用api接口，传入ak/sk/endpoint信息，返回token信息。

TokenInfo信息如下：

参数	类型	描述
Token	string	token 随机串
ExpireTime	long	过期时间，默认30分钟

获取TokenInfo这一步在Client 初始化时会自动调用RefreshToToken，用户默认可以不用进行这一步操作。同时在token过期前5分钟会再次去获取token。

示例代码：使用ak,sk去获取临时凭证token

RefreshToken();

4.3. 关于Log的操作

4.3.1. new logItem()

此操作用于生成待上传的日志，日志同步上传只能上传List格式的日志，logItems是一个List类型，里面包含若干条LogItem日志，LogItem格式如下：

参数	类型	描述	是否必须
timestamp	Int64	时间戳，单位纳秒	是
OriMsg	string	原始日志内容	是
contents	Dictionary<string, object>	日志内容，分词后的内容，可用于索引	否
labels	Dictionary<string, object>	自定义标签	否

new LogItem()时会自动设置一个当前的时间戳，如果希望自定义时间戳，可以主动赋值。

示例代码：组装生成10条日志

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()

此操作用于日志上传服务，需要传入的参数有三个，分别是logProject(日志项目编码)，logUnit(日志单元编码)，logItems（要上传的日志）。

参数	类型	描述	是否必须
logProject	string	日志项目编码	是
logUnit	string	日志单元编码	是
logItems	List	日志信息	是

示例代码：上传日志,默认使用lz4压缩

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

response 是Response格式的返回响应体，如下表格式：

参数	类型	描述	示例
statusCode	int	返回码，取值范围：0：-正常、-1：严重错误，其他自定义错误码
message	string	状态描述	SUCCESS
error	string	参考错误编码列表

日志服务相关错误编码(部分):

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