diff --git a/README.md b/README.md index f422c458..205cf771 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # SKIT.FlurlHttpClient.Wechat -基于 `Flurl.Http` 的微信 API HTTP 客户端，支持公众平台、开放平台、商户平台、企业微信等模块。 +基于 `Flurl.Http` 的微信 API HTTP 客户端，支持公众平台、开放平台、商户平台、企业微信、广告平台等模块。 > [`Flurl.Http`](https://flurl.dev/) 是一个轻量级 HTTP 库，是 .NET 中最受欢迎扩展库之一，在 NuGet 上的累计下载量超过 1700 万、日均下载量超过 6 千、GitHub 2.6k Stars（数据统计截至 2021-06-01）。 > @@ -38,7 +38,7 @@ | 公众平台（公众号、小程序） & 开放平台模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Api.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) | [文档](./docs/WechatApi/README.md) | | 商户平台（微信支付）模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.TenpayV3.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) | [文档](./docs/WechatTenpayV3/README.md) | | 企业微信（企业号）模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Work.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) | [文档](./docs/WechatWork/README.md) | -| 广告平台（广点通）模块 | _开发中_ | | +| 广告平台（广点通）模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Ads.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Ads.Work) | [文档](./docs/WechatAds/README.md) | --- diff --git a/docs/WechatAds/Advanced_AccessToken.md b/docs/WechatAds/Advanced_AccessToken.md new file mode 100644 index 00000000..3f07be72 --- /dev/null +++ b/docs/WechatAds/Advanced_AccessToken.md @@ -0,0 +1,11 @@ +### 如何获取接口调用凭据？ + +--- + +> 请先自行阅读： +> +> [《微信官方文档 - 开放平台：授权流程说明》](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/api/Before_Develop/Authorization_Process_Technical_Description.html) +> +> [《微信官方文档 - 开放平台：Token 生成说明》](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/api/Before_Develop/creat_token.html) + +该部分所需接口已由 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块提供，请开发者自行阅读相关文档。 \ No newline at end of file diff --git a/docs/WechatAds/Advanced_ModelDefinition.md b/docs/WechatAds/Advanced_ModelDefinition.md new file mode 100644 index 00000000..8f836b79 --- /dev/null +++ b/docs/WechatAds/Advanced_ModelDefinition.md @@ -0,0 +1,11 @@ +### 如何快速找到需要调用的 API 模型类名 / 方法名？ + +--- + +本库提供的请求模型、响应模型和接口方法，三者均保持同名。 + +例如，预估覆盖人数的请求是 `EstimationGetRequest`，响应是 `EstimationGetResponse`，接口是 `ExecuteEstimationGetAsync()`。知道其中一个，其余两个就可以快速地推断出了。 + +再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的预估覆盖人数，它的接口地址是 `[POST] /estimation/get`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。 + +完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Ads/Models_ 目录。 diff --git a/docs/WechatAds/README.md b/docs/WechatAds/README.md new file mode 100644 index 00000000..231c6dba --- /dev/null +++ b/docs/WechatAds/README.md @@ -0,0 +1,92 @@ +# SKIT.FlurlHttpClient.Wechat.Ads + +[![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Ads.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Ads) +[![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.Ads.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Ads) +[![GitHub License](https://img.shields.io/github/license/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE) + +基于 `Flurl.Http` 的[微信广告平台](https://ad.weixin.qq.com/) API 客户端。 + +需要注意的是，微信广告平台是腾讯广点通的独立业务，请开发者阅读相关文档时注意与广点通本身的 API 区分。 + +--- + +## 功能 + +- 基于微信广告平台 API 封装。 + +- 请求时自动生成服务商身份令牌，无需开发者手动干预。 + +- 提供了微信广告平台 API 所需的 MD5 等算法工具类。 + +- 完整微信广告平台 API 一览： + + | | 微信 API | 备注 | + | :-: | :------------: | :--: | + | √ | 广告帐号模块 | | + | √ | 资质管理模块 | | + | √ | 服务商权限模块 | | + | √ | 资金账户模块 | | + | √ | 推广计划模块 | | + | √ | 广告组模块 | | + | √ | 广告创意模块 | | + | √ | 广告模块 | | + | √ | 报表模块 | | + | √ | 异步任务模块 | | + | √ | 图片管理模块 | | + | √ | 客户人群管理 | | + | √ | 其他模块 | | + +--- + +## 基础用法 + +### 安装： + +提示：如果你使用 Visual Studio NuGet 管理器图形化界面，请在搜索结果中勾选“**包括预发行版**”。 + +```shell +# 通过 NuGet 安装 +> Install-Package SKIT.FlurlHttpClient.Wechat.Ads + +# 通过 dotnet-tools 安装 +> dotnet add package SKIT.FlurlHttpClient.Wechat.Ads +``` + +### 初始化： + +```csharp +using SKIT.FlurlHttpClient.Wechat; +using SKIT.FlurlHttpClient.Wechat.Ads; + +var options = new WechatAdsClientOptions() +{ + AgencyId = "广告服务商 ID", + AgencyAppId = "广告服务商 AppId", + AgencyApiKey = "广告服务商 ApiKey" +}; +var client = new WechatAdsClient(options); +``` + +### 请求 & 响应： + +```csharp +using SKIT.FlurlHttpClient.Wechat.Ads; +using SKIT.FlurlHttpClient.Wechat.Ads.Models; + +/* 示例：创建推广计划 */ +var request = new CampaignsAddRequest() +{ + AccessToken = "广告主的 AccessToken", + CampaignType = "CAMPAIGN_TYPE_WECHAT_OFFICIAL_ACCOUNTS", + ProductType = "PRODUCT_TYPE_LINK_WECHAT" +}; +var response = await client.ExecuteCampaignsAddAsync(request); +``` + +--- + +## 高级技巧 + +- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md) + +- [如何获取接口调用凭据（即 AccessToken）？](./Advanced_AccessToken.md) diff --git a/docs/WechatApi/README.md b/docs/WechatApi/README.md index 273246af..3373f4c0 100644 --- a/docs/WechatApi/README.md +++ b/docs/WechatApi/README.md @@ -4,19 +4,19 @@ [![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.Api.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) [![GitHub License](https://img.shields.io/github/license/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE) -基于 `Flurl.Http` 的微信公众平台 & 开放平台 API 客户端。 +基于 `Flurl.Http` 的[微信公众平台]((https://mp.weixin.qq.com/)) & [微信开放平台]((https://open.weixin.qq.com/)) API 客户端。 --- ## 功能 -- 基于微信公众平台 & 开放平台 API 封装。 +- 基于微信公众平台 & 微信开放平台 API 封装。 -- 提供了微信公众平台 & 开放平台 API 所需的 SHA-1、HMAC-SHA-256、AES 等算法工具类。 +- 提供了微信公众平台 & 微信开放平台 API 所需的 SHA-1、HMAC-SHA-256、AES 等算法工具类。 - 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。 -- 完整微信公众平台 & 开放平台 API 一览： +- 完整微信公众平台 & 微信开放平台 API 一览： | | 微信 API | 所属平台 | 备注 | | :-: | :----------------------------------: | :--------------------------: | :------------------: | diff --git a/docs/WechatTenpayV3/README.md b/docs/WechatTenpayV3/README.md index 7675cc40..50d2de41 100644 --- a/docs/WechatTenpayV3/README.md +++ b/docs/WechatTenpayV3/README.md @@ -4,7 +4,7 @@ [![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.TenpayV3.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) [![GitHub License](https://img.shields.io/github/license/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE) -基于 `Flurl.Http` 的微信支付 API v3 版客户端。 +基于 `Flurl.Http` 的[微信商户平台](https://pay.weixin.qq.com/) API v3 版客户端。 --- diff --git a/docs/WechatWork/README.md b/docs/WechatWork/README.md index f6229707..2140c3ad 100644 --- a/docs/WechatWork/README.md +++ b/docs/WechatWork/README.md @@ -4,7 +4,7 @@ [![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.Work.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) [![GitHub License](https://img.shields.io/github/license/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE) -基于 `Flurl.Http` 的企业微信 API 客户端。 +基于 `Flurl.Http` 的[企业微信](https://work.weixin.qq.com/) API 客户端。 ---