今日頭條Marketing API小工具(.Net Core版本)

前言

　　因爲工做緣由，須要用到今日頭條的Marketing API作一些廣告投放的定製化開發。而後看如今網上也沒多少關於頭條Marketing API的文章，因而便就有了該篇文章。

　　頭條Marketing API主頁地址：https://ad.toutiao.com/openapi/index.html。

　　頭條Marketing API開發文檔：https://ad.toutiao.com/openapi/doc/index.html

 

交互圖

　　典型的OAuth2.0受權流程：

　　

 

使用步驟

　　1. 首先須要去主頁註冊一個開發者帳號，並申請一個APPID，設置好回調地址

 　　由於從頭條重定向回本身的站點只是瀏覽器行爲，全部回調地址填寫本機可訪問的地址便可（不須要頭條能訪問），這裏是http://localhost:5000/api/auth/callback。

 

　　2. 在appsettings.json中設置APPID + Secret

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*",
  "toutiao": {
    "appId": "{Your appId}",
    "secret": "{Your secret}"
  } 
}

 

　　3. 啓動項目，便可直接在swagger中使用

　　

　　

 

程序邏輯

　　1. 在launchsettings.json中設置啓動地址爲http://localhost:5000/api/auth

"ToutiaoApi": {
  "commandName": "Project",
  "launchBrowser": true,
  "launchUrl": "api/auth",
  "applicationUrl": "http://localhost:5000",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

 

　　2. 瀏覽器訪問地址http://localhost:5000/api/auth，會重定向到今日頭條的認證地址，而且拼接好參數

[HttpGet]
public IActionResult Redirect()
{
    var authUrl = "http://ad.toutiao.com/openapi/audit/oauth.html";
    var redirectUrl = $"{Request.Scheme}://{Request.Host}/api/auth/callback";
    var url = $"{authUrl}?app_id={_setting.AppId}&state=&scope=[\"ad_service\",\"report_service\",\"dmp_service\",\"account_service\"]&redirect_uri={redirectUrl}";
    return Redirect(url);
}

 

　　3. 跳轉到今日頭條的認證地址並點擊「贊成受權」

 

　　4. 重定向回http://localhost:5000/api/auth/callback並帶回了auth_code參數

　　

 

　　5. 利用AuthCode + AppId + Secret調用頭條認證API獲取AccessToken，並把AccessToken緩存到內存中，而後重定向回swagger

[HttpGet("callback")]
public async Task<IActionResult> Callback([FromQuery(Name = "auth_code")]string authCode)
{
    var url = "https://ad.toutiao.com/open_api/oauth2/access_token/";

    var request = new AuthRequest
    {
        AppId = _setting.AppId,
        Secret = _setting.Secret,
        AuthCode = authCode
    };

    var response = await _restClient.PostAsync<AuthResponse>(url, request);
    response.EnsureSuccess();

    _cache.Set(ToutiaoCacheKey.AccessToken, response.Data.AccessToken);
    return Redirect("/swagger/index.html");
}

 

調用頭條API

　　0. 示例代碼

/// <summary>
/// 獲取廣告計劃（新版）
/// </summary>
/// <param name="advertiserId">廣告主ID</param>
/// <param name="page">頁數，默認值: 1</param>
/// <param name="pageSize">頁面大小，默認值: 10，最大值：100</param>
/// <returns></returns>
[HttpGet("get")]
public async Task<IActionResult> Get([FromQuery] string advertiserId, [FromQuery]int page = 1, [FromQuery]int pageSize = 10)
{
    var url = "https://ad.toutiao.com/open_api/2/ad/get/" + "?advertiser_id=" + advertiserId + "&page=" + page + "&page_size=" + pageSize;
    var response = await _restClient.GetAsync<DynamicResponse>(url, _cache.Get<string>(ToutiaoCacheKey.AccessToken));
    response.EnsureSuccess();
    return Ok(response);
}

 

　　1. 根據文檔拼接對應參數

var url = "https://ad.toutiao.com/open_api/2/ad/get/" + "?advertiser_id=" + advertiserId + "&page=" + page + "&page_size=" + pageSize;

 

　　2. 從緩存中取出以前獲得的AccessToken

_cache.Get<string>(ToutiaoCacheKey.AccessToken)

 

　　3. 構造請求頭信息

client.DefaultRequestHeaders.Add("Access-Token", accessToken);

 

　　4. 調用API，並把返回的json反序列化爲dynamic類型

var response = await _restClient.GetAsync<DynamicResponse>(url, _cache.Get<string>(ToutiaoCacheKey.AccessToken));

 

　　5. 輸出結果到瀏覽器

　　說明：示例中只有查詢類API，沒有操做類型的API，主要是考慮到操做可能會影響到現有業務。

 

操做類型API

　　代碼調用操做類型的API時，可能須要構建請求json對應的實體，這裏可使用Visual Studio的選擇性編輯功能，快速生成對象。

　　示例：

　　1. 拷貝json

{
    "advertiser_id": 0,
    "campaign_name": "xxx",
    "budget": 1000,
    "landing_type": "LINK",
    "budget_mode": "BUDGET_MODE_DAY"
}

 

　　2. 新建一個cs文件，點擊Visual Studio菜單欄的「編輯」 -> 「選擇性編輯」 -> 「保存json爲類」

　　

　　

 

　　3. 設置JsonProperty（可選，規範、美觀考慮）

　　

 

　　其實，頭條的開發文檔中有提供操做API的示例json，可是示例json的字段有些不全，而請求API的結果基本包含了操做API的字段。

　　所以，可使用操做API的返回json來生成操做請求。同時，這個小工具也能夠作一些前期的簡單查詢。

 

源碼地址

　　https://github.com/ErikXu/ToutiaoApi