From 20013904ee66b8b28d004809df24f3f1940dd86a Mon Sep 17 00:00:00 2001 From: Fu Diwei Date: Tue, 5 Mar 2024 14:45:52 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/MicroApp/Advanced_Dispose.md | 13 +++ docs/MicroApp/Advanced_IHttpClientFactory.md | 4 +- docs/MicroApp/Advanced_Interceptor.md | 2 +- docs/MicroApp/Advanced_JsonSerializer.md | 2 +- docs/MicroApp/Basic_EventDeserialization.md | 20 ++-- .../Basic_EventSignatureVerification.md | 19 ++-- docs/MicroApp/Basic_Extensions.md | 20 ++-- docs/MicroApp/Basic_ModelDefinition.md | 10 +- docs/MicroApp/README.md | 97 ++++++++++++------- 9 files changed, 112 insertions(+), 75 deletions(-) create mode 100644 docs/MicroApp/Advanced_Dispose.md diff --git a/docs/MicroApp/Advanced_Dispose.md b/docs/MicroApp/Advanced_Dispose.md new file mode 100644 index 00000000..cf2f55e3 --- /dev/null +++ b/docs/MicroApp/Advanced_Dispose.md @@ -0,0 +1,13 @@ +## 如何销毁客户端？ + +--- + +本功能来自于公共组件，请参阅公共组件下的相关文档： + +> [《SKIT.FlurlHttpClient FAQ：如何销毁客户端（避免内存泄漏）？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/README.md) + +--- + +### 镜像站点 + +国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。 diff --git a/docs/MicroApp/Advanced_IHttpClientFactory.md b/docs/MicroApp/Advanced_IHttpClientFactory.md index d73d446a..48061b9b 100644 --- a/docs/MicroApp/Advanced_IHttpClientFactory.md +++ b/docs/MicroApp/Advanced_IHttpClientFactory.md @@ -1,10 +1,10 @@ -## 如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？ +## 如何与 `IHttpClientFactory` 集成？ --- 本功能来自于公共组件，请参阅公共组件下的相关文档： -> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md) +> [《SKIT.FlurlHttpClient FAQ：如何与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/README.md) --- diff --git a/docs/MicroApp/Advanced_Interceptor.md b/docs/MicroApp/Advanced_Interceptor.md index 2bc28620..23f63eb1 100644 --- a/docs/MicroApp/Advanced_Interceptor.md +++ b/docs/MicroApp/Advanced_Interceptor.md @@ -4,7 +4,7 @@ 本功能来自于公共组件，请参阅公共组件下的相关文档： -> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md) +> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/README.md) --- diff --git a/docs/MicroApp/Advanced_JsonSerializer.md b/docs/MicroApp/Advanced_JsonSerializer.md index a9df787e..251fe34f 100644 --- a/docs/MicroApp/Advanced_JsonSerializer.md +++ b/docs/MicroApp/Advanced_JsonSerializer.md @@ -4,7 +4,7 @@ 本功能来自于公共组件，请参阅公共组件下的相关文档： -> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md) +> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/README.md) --- diff --git a/docs/MicroApp/Basic_EventDeserialization.md b/docs/MicroApp/Basic_EventDeserialization.md index 35e37bc8..8f8567e7 100644 --- a/docs/MicroApp/Basic_EventDeserialization.md +++ b/docs/MicroApp/Basic_EventDeserialization.md @@ -2,46 +2,46 @@ --- -对于字节小程序推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： +对于抖音小程序推送过来的回调通知事件，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： ```csharp /* 如果是 JSON 格式的通知内容，以 text 事件为例 */ -string callbackJson = "{ ... }"; -var callbackModel = client.DeserializeEventFromJson(callbackJson); +string webhookJson = "{ ... }"; +var webhookModel = client.DeserializeEventFromJson(webhookJson); /* 如果是 XML 格式的通知内容，以 text 事件为例 */ -string callbackXml = " ... "; -var callbackModel = client.DeserializeEventFromXml(callbackXml); +string webhookXml = " ... "; +var webhookModel = client.DeserializeEventFromXml(webhookXml); ``` -完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.ByteDance.MicroApp/Events_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/ProductApi/Events_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/OpenApi/Events_ 目录。 +完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.ByteDance.MicroApp/Events_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/OpenApi/Events_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/ProductApi/Events_ 目录。 --- ### 事件类型： -由于字节小程序会将全部事件推送到同一个回调通知地址上，开发者需要根据事件类型才能决定如何反序列化。 +由于抖音小程序会将全部事件推送到同一个回调通知地址上，开发者需要根据事件类型才能决定如何反序列化。 这里给出两种解决方案。 一种是利用 `System.Xml.Linq`： ```csharp -XDocument xDoc = XDocument.Parse(callbackXml); +XDocument xDoc = XDocument.Parse(webhookXml); string msgType = xDoc.Root?.Element("MsgType")?.Value?.ToUpper(); ``` 另一种是利用本库的扩展方法： ```csharp -ByteDanceMicroAppEvent eventModel = client.DeserializeEventFromXml(callbackXml); +ByteDanceMicroAppEvent eventModel = client.DeserializeEventFromXml(webhookXml); string msgType = eventModel.MessageType?.ToUpper(); switch (msgType) { case "TEXT": { - var callbackModel = client.DeserializeEventFromXml(callbackXml); + var webhookModel = client.DeserializeEventFromXml(webhookXml); } break; // 省略其他情况 diff --git a/docs/MicroApp/Basic_EventSignatureVerification.md b/docs/MicroApp/Basic_EventSignatureVerification.md index e6c0bf9c..a7661713 100644 --- a/docs/MicroApp/Basic_EventSignatureVerification.md +++ b/docs/MicroApp/Basic_EventSignatureVerification.md @@ -4,25 +4,24 @@ > 请先自行阅读： > -> [《字节小程序文档 - 消息推送客服：验证消息来自今日头条》](https://microapp.bytedance.com/docs/zh-CN/mini-app/develop/component/message-push-customer-service) +> [《抖音小程序文档 - 消息推送客服：验证消息来自今日头条》](https://microapp.bytedance.com/docs/zh-CN/mini-app/develop/component/message-push-customer-service) 同样的，你既可以利用本库提供的 `SHA1Utility` 工具类自行进行签名验证，也可以通过扩展方法实现： ```csharp /* 在初始化客户端时需指定服务器推送的相关参数 */ -var options = new ByteDanceMicroAppClientOptions() +var options = new DouyinMicroAppClientOptions() { - AppId = "字节小程序 AppId", - AppSecret = "字节小程序 AppSecret", + // 其他配置项略 PushToken = "服务器推送的 Token" }; -var client = new ByteDanceMicroAppClient(options); +var client = DouyinMicroAppClientBuilder.Create(options).Build(); -/* 验证字节小程序服务器 */ +/* 验证抖音服务器 */ bool ret = client.VerifyEventSignatureForEcho( - callbackTimestamp: "字节小程序回调通知中的 timestamp 字段", - callbackNonce: "字节小程序回调通知中的 nonce 字段", - callbackMessage: "头条回调通知中的 msg 字段", - callbackSignature: "头条回调通知中的 signature 字段" + webhookTimestamp: "抖音小程序回调通知中的 timestamp 字段", + webhookNonce: "抖音小程序回调通知中的 nonce 字段", + webhookMsg: "抖音回调通知中的 msg 字段", + webhookSignature: "抖音回调通知中的 signature 字段" ); ``` diff --git a/docs/MicroApp/Basic_Extensions.md b/docs/MicroApp/Basic_Extensions.md index ab08244d..855bd998 100644 --- a/docs/MicroApp/Basic_Extensions.md +++ b/docs/MicroApp/Basic_Extensions.md @@ -5,26 +5,26 @@ 如果有某些接口本库尚未支持，你可按照下面的示例自行扩展： ```csharp -/* 继承 ByteDanceMicroAppRequest 实现自定义请求类 */ -public class MyFakeRequest : ByteDanceMicroAppRequest +/* 继承 DouyinMicroAppRequest 实现自定义请求类 */ +public class MyFakeRequest : DouyinMicroAppRequest { [Newtonsoft.Json.JsonProperty("my_fake_props")] [System.Text.Json.Serialization.JsonPropertyName("my_fake_props")] public string MyFakeProps { get; set; } } -/* 继承 ByteDanceMicroAppResponse 实现自定义响应类 */ -public class MyFakeResponse : ByteDanceMicroAppResponse +/* 继承 DouyinMicroAppResponse 实现自定义响应类 */ +public class MyFakeResponse : DouyinMicroAppResponse { [Newtonsoft.Json.JsonProperty("my_fake_props")] [System.Text.Json.Serialization.JsonPropertyName("my_fake_props")] public string MyFakeProps { get; set; } } -/* 扩展 ByteDanceMicroAppClient 方法 */ +/* 扩展 DouyinMicroAppClient 方法 */ public static class MyFakeClientExtensions { - public static async Task ExecuteMyFakeAsync(this ByteDanceMicroAppClient client, MyFakeRequest request, CancellationToken cancellationToken = default) + public static async Task ExecuteMyFakeAsync(this DouyinMicroAppClient client, MyFakeRequest request, CancellationToken cancellationToken = default) { if (client is null) throw new ArgumentNullException(nameof(client)); if (request is null) throw new ArgumentNullException(nameof(request)); @@ -41,16 +41,16 @@ public static class MyFakeClientExtensions 同样的，你也可自行扩展回调通知事件模型： ```csharp -/* 继承 ByteDanceMicroAppEvent 实现自定义的 JSON 格式的回调通知事件 */ -public class MyFakeEvent : ByteDanceMicroAppEvent, ByteDanceMicroAppEvent.Serialization.IJsonSerializable +/* 继承 DouyinMicroAppEvent 实现自定义的 JSON 格式的回调通知事件 */ +public class MyFakeEvent : DouyinMicroAppEvent, DouyinMicroAppEvent.Serialization.IJsonSerializable { [Newtonsoft.Json.JsonProperty("my_fake_props")] [System.Text.Json.Serialization.JsonPropertyName("my_fake_props")] public string MyFakeProps { get; set; } } -/* 继承 ByteDanceMicroAppEvent 实现自定义的 XML 格式的回调通知事件 */ -public class MyFakeEvent : ByteDanceMicroAppEvent, ByteDanceMicroAppEvent.Serialization.IXmlSerializable +/* 继承 DouyinMicroAppEvent 实现自定义的 XML 格式的回调通知事件 */ +public class MyFakeEvent : DouyinMicroAppEvent, DouyinMicroAppEvent.Serialization.IXmlSerializable { [System.Xml.Serialization.XmlElement("my_fake_props")] public string MyFakeProps { get; set; } diff --git a/docs/MicroApp/Basic_ModelDefinition.md b/docs/MicroApp/Basic_ModelDefinition.md index 68b68ac0..e127711d 100644 --- a/docs/MicroApp/Basic_ModelDefinition.md +++ b/docs/MicroApp/Basic_ModelDefinition.md @@ -8,11 +8,11 @@ 再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发送订阅消息，它的接口地址是 `[POST] /apps/message/custom/send`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。如果路由中带有版本信息，那么版本号一般都在结尾处，例如接口 `[POST] /v2/tags/image` 对应的是 `TagsImageV2`。 -完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.ByteDance.Api/Models_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/ProductApi/Models_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/OpenApi/Models_ 目录。 +完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.ByteDance.Api/Models_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/OpenApi/Models_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/ProductApi/Models_、_src/SKIT.FlurlHttpClient.ByteDance.Api/SDK/RoleApi/Models_ 目录。 --- -### 字节小程序开放平台 API 支持情况： +### 抖音小程序开放平台 API 支持情况： #### 1. 小程序 @@ -20,7 +20,7 @@ [展开查看] -| | 字节 API | 备注 | +| | 抖音 API | 备注 | | :-: | :------------------------------------: | :------------------: | | √ | 接口调用凭证 | | | √ | 登录 | | @@ -50,7 +50,7 @@ [展开查看] -| | 字节 API | 备注 | +| | 抖音 API | 备注 | | :-: | :----------: | :--: | | √ | 接口调用凭证 | | | √ | 登录 | | @@ -66,7 +66,7 @@ [展开查看] -| | 字节 API | 备注 | +| | 抖音 API | 备注 | | :-: | :--------------------: | :--: | | √ | 授权相关接口 | | | √ | 域名相关接口 | | diff --git a/docs/MicroApp/README.md b/docs/MicroApp/README.md index 63564402..23d7d775 100644 --- a/docs/MicroApp/README.md +++ b/docs/MicroApp/README.md @@ -1,19 +1,22 @@ # SKIT.FlurlHttpClient.ByteDance.MicroApp -基于 `Flurl.Http` 的[字节小程序开放平台](https://microapp.bytedance.com/) HTTP API SDK。 +基于 `Flurl.Http` 的[抖音小程序开放平台](https://microapp.bytedance.com/) HTTP API SDK。 --- ## 功能 -- 基于字节小程序开放平台 API 封装。 -- 提供了字节小程序所需的 AES、MD5、SHA-1、HMAC-SHA-256 等算法工具类。 +- 基于抖音小程序开放平台 API 封装。 +- 提供了抖音小程序所需的 AES、MD5、SHA-1、HMAC-SHA-256 等算法工具类。 - 提供了解析回调通知事件等扩展方法。 --- ## 快速入门 +> [!IMPORTANT] +> 此目录下的文档适用于 v3.x 版本的模块。如果你正在使用 2.x 版本，请移步至 GitHub/Gitee 的已归档分支。 + ### 安装： 提示：如果你使用 Visual Studio NuGet 管理器图形化界面，请在搜索结果中勾选“**包括预发行版**”。 @@ -29,41 +32,16 @@ ### 初始化： ```csharp -/* 以基础 API 为例 */ using SKIT.FlurlHttpClient.ByteDance.MicroApp; -var options = new ByteDanceMicroAppClientOptions() +var options = new DouyinMicroAppClientOptions() { - Endpoints = ByteDanceMicroAppEndpoints.API_MINIAPP, // 指定接入点。需注意小程序、小游戏拥有不同的接入点。 - AppId = "字节小程序 AppId", - AppSecret = "字节小程序 AppSecret", + Endpoints = DouyinMicroAppEndpoints.API_MINIAPP, // 指定接入点。需注意小程序、小游戏拥有不同的接入点。 + AppId = "抖音小程序 AppId", + AppSecret = "抖音小程序 AppSecret", ECPaySalt = "担保支付相关服务的密钥，不用则不填" }; -var client = new ByteDanceMicroAppClient(options); - - - -/* 以泛知识课程库 API 为例 */ -using SKIT.FlurlHttpClient.ByteDance.MicroApp.SDK.ProductApi; - -var options = new ByteDanceMicroAppProductApiClientOptions() -{ - AppId = "字节小程序 AppId", - AppSecret = "字节小程序 AppSecret" -}; -var client = new ByteDanceMicroAppProductApiClient(options); - - - -/* 以服务商平台 API 为例 */ -using SKIT.FlurlHttpClient.ByteDance.MicroApp.SDK.OpenApi; - -var options = new ByteDanceMicroAppOpenApiClientOptions() -{ - ComponentAppId = "字节小程序第三方应用 AppId", - ComponentAppSecret = "字节小程序第三方应用 AppSecret" -}; -var client = new ByteDanceMicroAppOpenApiClient(options); +var client = DouyinMicroAppClientBuilder.Create(options).Build(); ``` ### 请求 & 响应： @@ -92,11 +70,56 @@ else } ``` +### 独立的（服务商平台、泛知识课程库、泛知识角色系统等）扩展客户端： + +部分 API 的接入点、接口模型公共参数等配置项与基础 API 完全不同，需要使用独立的扩展客户端。 + +- 服务商平台： + +```csharp +using SKIT.FlurlHttpClient.ByteDance.MicroApp.SDK.OpenApi; + +var options = new DouyinMicroAppOpenApiClientOptions() +{ + ComponentAppId = "第三方应用 AppId", + ComponentAppSecret = "第三方应用 AppSecret" +}; +var client = DouyinMicroAppOpenApiClientBuilder.Create(options).Build(); +``` + +- 泛知识课程库： + +```csharp +using SKIT.FlurlHttpClient.ByteDance.MicroApp.SDK.ProductApi; + +var options = new DouyinMicroAppProductApiClientOptions() +{ + AppId = "抖音小程序 AppId", + AppSecret = "抖音小程序 AppSecret" +}; +var client = DouyinMicroAppProductApiClientBuilder.Create(options).Build(); +``` + +- 泛知识角色系统： + +```csharp +using SKIT.FlurlHttpClient.ByteDance.MicroApp.SDK.RoleApi; + +var options = new DouyinMicroAppRoleApiClientOptions() +{ + AppId = "抖音小程序 AppId", + AppSecret = "抖音小程序 AppSecret" +}; +var client = DouyinMicroAppRoleApiClientBuilder.Create(options).Build(); +``` + +这些扩展客户端在用法上基础客户端完全相同，只需引入各自的命名空间即可。 + --- ## 基础用法 -- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Basic_ModelDefinition.md) +- ⭐ [如何快速找到需要调用的 API 模型类名 / 方法名？](./Basic_ModelDefinition.md) - [如何解析回调通知事件？](./Basic_EventDeserialization.md) @@ -106,9 +129,11 @@ else --- -## 快速高级技巧入门 +## 高级技巧 + +- [如何销毁客户端？](./Advanced_Dispose.md) -- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) +- [如何与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)