SyncHTTP プッシュの設定（推奨）

​

コールバックの概要

• RDS プッシュ
• HTTP プッシュ
• SyncHTTP プッシュ

• 203.119.0.0/16
• 203.119.128.0/17
• 140.205.0.0/16
• 106.11.0.0/16
• 198.11.0.0/16
• 59.82.0.0/16

​

コールバックイベントの登録フロー

​

リクエストエンドポイントの設定とコールバックイベントのサブスクライブ

1. Developer Console にログインします。作成したアプリを検索し、その詳細ページを開きます。
2. Development Management をクリックし、次に Edit をクリックして、プッシュタイプとして SyncHTTP Push を選択します。
3. リクエストを受信するための HTTP エンドポイントを設定します。
   • token: DingTalk がエンドポイントにイベントデータをプッシュするたびに、Signature を生成しコールバックリクエストの正当性を検証するために使用する token が含まれます。英字または数字で構成し、3〜32 文字の長さである必要があります。
   • Encryption AES Key: Generate Automatically をクリックして AES キーを生成します。これはコールバックメッセージのコンテンツを暗号化・復号するために使用するパラメータです。AES キーの Base64 エンコードです。詳細は後述のメッセージの暗号化と復号を参照してください。
   • Callback URL: サブスクライブしたイベントのリクエストを受信するために使用する URL です。サブスクライブしたイベントがトリガーされると、DingTalk はこの URL に対応する HTTP POST リクエストを送信します。 注意 各アプリには 1 つのコールバック URL しか設定できません。アプリのサブスクリプションに対するすべてのイベント通知は、このリクエスト URL に送信されます。
4. 設定が完了した後、Verify Validity ボタンをクリックすると、Open Platform は設定した URL に application/json の POST リクエストをプッシュして、その正当性を検証します。以下に示します。
   {
       "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   // 暗号化文字列。後述の暗号化・復号の説明を参照してください。
   }
   
   Open Platform から POST 検証リクエストを受信したら、それを復号し、1,200 ms 以内に success を含む暗号化文字列を DingTalk に返してください。時間内に応答しない場合、リクエストがレート制限される可能性があります。
5. リクエストエンドポイントの設定が正常に完了した後、Callback Events リストエリアで、サブスクライブしたいコールバックイベントを選択し、右上の Save をクリックします。 注意 コールバックイベントを選択できない場合は、Developer Console の Manage Permissions ページで対応する API 権限を申請してください。

​

プッシュデータの説明

{
    "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   // 暗号化文字列。後述の暗号化・復号の説明を参照してください。
}

• check_url: テストコールバックイベント 復号後のデータ:
  {
      "EventType" : "check_url"
  }
  
• check_create_suite_url: 検証コールバックイベント 復号後のデータ:
  {
    "EventType":"check_create_suite_url",
    "Random":"brdkKLMW"
  }
  
• check_update_suite_url: コールバック URL 更新イベント 復号後のデータ:
  {
    "EventType":"check_update_suite_url",
    "Random":"xxxxxx",
    "TestSuiteKey":"suited6db0pze8yao1b1y"
  }
  
• SYNC_HTTP_PUSH_HIGH: アプリ有効化などの高優先度データ
  {
   "EventType": "SYNC_HTTP_PUSH_HIGH",
   "bizData": [{
    "gmt_create": 1608639648000,
    "biz_type": 4,
    "open_cursor": 0,
    "subscribe_id": "14999999001_0",
    "id": 7001,
    "gmt_modified": 1608639648000,
    "biz_id": "1489999001",
    "biz_data": "{\"auth_user_info\":{\"userId\":\"manager4xxx\"},\"auth_corp_info\":{\"corp_type\":0,\"corpid\":\"dingffea2a0dcc37d0xxxxxxx25e91351\",\"auth_level\":0,\"auth_channel\":\"\",\"industry\":\"\",\"full_corp_name\":\"XX テスト組織\",\"corp_name\":\"XX テスト組織\",\"invite_url\":\"https://pre-wx.dingtalk.com/xxxxx/index.html?bizSource=____source____&corpId=dingffea2a0dcc3xxxxx25e91351&inviterUid=71E7E5B48C2DDB2xxxxxxF52346D\",\"auth_channel_type\":\"\",\"invite_code\":\"\",\"is_authenticated\":false,\"license_code\":\"\",\"corp_logo_url\":\"\"},\"syncAction\":\"org_suite_auth\",\"auth_scope\":{\"errcode\":0,\"condition_field\":[],\"auth_user_field\":[\"jobnumber\",\"isLeader\",\"name\",\"position\",\"isAdmin\",\"avatar\",\"department\",\"userid\",\"deviceId\",\"isHide\"],\"auth_org_scopes\":{\"authed_user\":[],\"authed_dept\":[1]},\"errmsg\":\"ok\"},\"auth_info\":{\"agent\":[{\"agentid\":1038226450,\"agent_name\":\"Tuhao Push Test 1217\",\"logo_url\":\"https://static-legacy.dingtalk.com/media/lADPDfmVQafoVxxxxxx0_200.jpg\",\"appid\":62282,\"admin_list\":[\"manager492\"]}]},\"permanent_code\":\"MFcbac-7zg0Mhcl-_dGmY2_f4NZPzLUf813xxxxxrjyEoGmKjqZwfi-5mh\"}",
    "corp_id": "dingffea2axxxxxx0dcb25e91351",
    "status": 0
   }]
  }
  
• SYNC_HTTP_PUSH_MEDIUM: 連絡先の変更などの通常優先度データ
  {
   "EventType": "SYNC_HTTP_PUSH_MEDIUM",
   "bizData": [{
    "gmt_create": 1608639751000,
    "biz_type": 14,
    "open_cursor": 0,
    "subscribe_id": "14778001_0",
    "id": 68,
    "gmt_modified": 1608639751000,
    "biz_id": "433877002",
    "biz_data": "{\"errcode\":0,\"userPermits\":\"\",\"userPerimits\":\"\",\"syncAction\":\"org_dept_create\",\"outerDept\":false,\"errmsg\":\"ok\",\"deptManagerUseridList\":\"\",\"parentid\":1,\"groupContainSubDept\":false,\"outerPermitUsers\":\"\",\"outerPermitDepts\":\"\",\"deptPerimits\":\"\",\"createDeptGroup\":true,\"name\":\"f'f'f\",\"id\":433885002,\"autoAddUser\":true,\"deptHiding\":false,\"deptPermits\":\"\",\"order\":43388775002}",
    "corp_id": "ding7629a25dxxxxxxxxf7214b6d69",
    "status": 0
   }]
  }
  

​

コールバックイベントの受信と応答

package com.controller;
import com.dingtalk.oapi.lib.aes.DingTalkEncryptor;
import org.springframework.web.bind.annotation.*;

/**
 * ISV ミニプログラムのコールバック処理
 */
@RestController
@RequestMapping("/")
public class CallbackController {

    private final Logger log = LoggerFactory.getLogger(getClass());

    @PostMapping(value = "dingCallback")
    public Object dingCallback(
            @RequestParam(value = "signature") String signature,
            @RequestParam(value = "timestamp") Long timestamp,
            @RequestParam(value = "nonce") String nonce,
            @RequestBody(required = false) JSONObject body
    ) {
        String[] config = CommonUtil.readConfig();
        String params = "signature:" + signature + " timestamp:" + timestamp + " nonce:" + nonce + " body:" + body;
        DingTalkEncryptor dingTalkEncryptor = new DingTalkEncryptor(config[CommonUtil.TOKEN], config[CommonUtil.ENCODING_AES_KEY], config[CommonUtil.SUITE_KEY]);

        // POST リクエストボディから暗号化されたコールバックデータを取得して復号します。後述のメッセージ暗号化・復号の説明を参照してください。
        String encrypt = body.getString("encrypt");
        String plainText = dingTalkEncryptor.getDecryptMsg(signature, timestamp.toString(), nonce, encrypt);
        JSONObject callBackContent = JSON.parseObject(plainText);

        // コールバックイベントタイプに応じて異なる業務処理を実行します
        String eventType = callBackContent.getString("EventType");
        //TODO データを永続化します
        return plainText;
    }
}

​

メッセージの暗号化と復号

• random は 16 バイトのランダム文字列です。
• msg_len は msg の 4 バイトの長さで、ネットワークバイトオーダーです。
• msg はメッセージ本文のプレーンテキストです。
• key はアプリの suiteKey です。

• 暗号文を Base64 デコードします: aes_msg = Base64_Decode(encrypt)。
• AESKey を使用して AES 復号を実行します: rand_msg = AES_Decrypt(aes_msg)。

public Map<String, String> callBack(HttpServletRequest request,
                                    @RequestParam(value = "msg_signature", required = false) String msg_signature,
                                    @RequestParam(value = "timestamp", required = false) String timeStamp,
                                    @RequestParam(value = "nonce", required = false) String nonce,
                                    @RequestBody(required = false) JSONObject json) {
    try {
        // 1. HTTP リクエストから暗号化・復号パラメータを取得します

        // 2. 暗号化・復号タイプを使用します
        // Constant.OWNER_KEY に関する注意事項:
        // 1. Developer Console で設定したサブスクリプションイベントがアプリレベルのイベントプッシュの場合、
        //      OWNER_KEY はアプリの APP_KEY（社内アプリ）または SUITE_KEY（サードパーティアプリ）です。
        // 2. イベントサブスクリプション API を通じてサブスクライブしたイベントが企業レベルのイベントプッシュの場合、
        //      OWNER_KEY は企業の CORP_ID（社内アプリ）または SUITE_KEY（サードパーティアプリ）です。
        DingCallbackCrypto callbackCrypto = new DingCallbackCrypto(Constant.AES_TOKEN, Constant.AES_KEY, Constant.OWNER_KEY);
        String encryptMsg = json.getString("encrypt");
        String decryptMsg = callbackCrypto.getDecryptMsg(msg_signature, timeStamp, nonce, encryptMsg);

        // 3. コールバックイベントの JSON データをデシリアライズします
        JSONObject eventJson = JSON.parseObject(decryptMsg);
        String eventType = eventJson.getString("EventType");

        // 4. EventType に応じて処理します
        bizLogger.info("Event occurred: " + eventType);

        // 5. 暗号化された "success" データを返します
        Map<String, String> successMap = callbackCrypto.getEncryptedMap("success");
        return successMap;

    } catch (DingTalkEncryptException e) {
        e.printStackTrace();
    }
    return null;
}