钉钉批改网合作

合作 接口

1.约定

1.1请求方式

请求使用POST请求；openKey 要使用对称加密。 请求和数据传输使用 JSON。

POST http://url.com/api?sign=签名

1.2签名

提交过来的json字符串 跟 openKey 加密

<?php
$str= file_get_contents("php://input");
$sign = md5($str . $openKey);

1.3统一返回格式

2.授权用户

参考
https://ding-doc.dingtalk.com/doc#/serverapi3/hv357q
https://ding-doc.dingtalk.com/doc#/serverapi3/mrugr3

3.老师作文题目授权与同步

post http://url.com/ding/request?sign=签名

作文公式（formula）对应表

返回体

{
    "error": 0,
    "errorDes": "",
    "data": {
        "dingWorkId":"1234",
        "pigaiWorkId":"1234" 
    }
}

4.学生提交作文授权

post http://url.com/ding/essay?sign=签名

{
    "error": 0,
    "errorDes": "",
    "data": {
        "dingEssayId": "d-pigai-1234"
    }
}

提交成功后
批改网的 作文内容ID 跟分析结果会异步提交返回

5.作文异步分析返回

钉钉需要提供异步接收接口

POST http://30.40.210.45:7001/pigai/sync/callback/work?sign=XXXX

返回

返回的pigaiAnalysis

{
    "score": 79.5, //总得分 满分来自设置
    "score100": 79.5, //总得分 满分100
    "scoreCat": { //四个维度
        "1": {
            "name": "词汇",
            "score": 0.8426485
        },
        "2": {
            "name": "句子",
            "score": 0.74554825
        },
        "3": {
            "name": "篇章结构",
            "score": 0.7881277
        },
        "4": {
            "name": "内容相关",
            "score": 0.7233994
        }
    },
    "comment": "采用了适当的衔接手法，层次清晰；句式变化多样，句法方面做的很棒；作者词汇基本功很好，高级词汇表达也比较恰当。", //总评
    "sentences": [
        {
            "sid": 0, // 第几句, 从0开始
            "pid": 1, // 段落, 从1开始
            "text": "Firstly, no accomplishment can be achieved in a transitory time, and success asks for continuous industrious work and efforts.",
            "comment": [
                {
                    "class": "error_trp",
                    // 四大类: warn 警告，error 错误，error_trp 提示，great 好
                    "cat": "学习提示",
                    "msg": "易混词汇: <b>effort</b>, trouble, pains, endeavour, struggle 均表示“努力”之意。",
                    "word_list": "efforts", //关键词
                    "rank": 0
                }
            ]
        },
        {
            "sid": 1,
            "pid": 1,
            "text": "One can taste the feeling of success only when he is more diligent than others.",
            "comment": [
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>only</b> :&nbsp;<span class='suggest'>just/merely/barely/singly/solely/rarely</span>",
                    "word_list": "only",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "学习提示",
                    "msg": "易混词汇: <b>diligent</b>, industrious 均表示“勤奋的”之意。",
                    "word_list": "diligent",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 2,
            "pid": 1,
            "text": "It is not only an attempt to theory discussion, but also the need of practice.",
            "comment": [
                {
                    "class": "error_trp",
                    "cat": "学习提示",
                    "msg": "易混词汇: drill, exercise, <b>practice</b>, training, discipline 都有“练习，训练，锻炼”之意。",
                    "word_list": "practice",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 3,
            "pid": 1,
            "text": "As the saying goes,\"Genius only means hard-working all one's life.\"",
            "comment": [
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>hard-working</b> :&nbsp;<span class='suggest'>diligent/assidious/industrious</span>",
                    "word_list": "hard-working",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "动名搭配 mean...life 在语料库中出现过<a target=\"_blank\" href=\"http://www.pigai.org/corpus/snt/?q=mean life/von\"> 34</a> 次",
                    "word_list": "",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>only</b> :&nbsp;<span class='suggest'>just/merely/barely/singly/solely/rarely</span>",
                    "word_list": "only",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>hard-working</b> :&nbsp;<span class='suggest'>assiduous</span>",
                    "word_list": "hard-working",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 4,
            "pid": 1,
            "text": "From my own perspective, firstly, efforts is more important, if you have not acquired the knowledge, your talent will not be used, but will be devoid of silence.",
            "comment": [
                {
                    "class": "error",
                    "cat": "句子错误",
                    "msg": "请检查<b>is</b>，确认主谓一致。",
                    "word_list": "is",
                    "rank": 100
                },
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>if</b> :&nbsp;<span class='suggest'>provided that</span>",
                    "word_list": "if",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "动名搭配 acquire...knowledge 在语料库中出现过<a target=\"_blank\" href=\"http://www.pigai.org/corpus/snt/?q=acquire knowledge/von\"> 37</a> 次",
                    "word_list": "",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 5,
            "pid": 1,
            "text": "To name only a few, Edison said,\"Success is 1% inspiration and perspiration\".",
            "comment": [
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>only</b> :&nbsp;<span class='suggest'>just/merely/barely/singly/solely/rarely</span>",
                    "word_list": "only",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "学习提示",
                    "msg": "易混词汇: little, <b>few</b>, several 均含“少量的”之意。",
                    "word_list": "few",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 6,
            "pid": 1,
            "text": "It demonstrates the importance of hard-working.",
            "comment": [
                {
                    "class": "warn",
                    "cat": "语法警示",
                    "msg": "确认<b>of hard-working</b>符合语法规范。",
                    "word_list": "of hard-working .",
                    "rank": 99
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "动名搭配 demonstrate...importance 在语料库中出现过<a target=\"_blank\" href=\"http://www.pigai.org/corpus/snt/?q=demonstrate importance/von\"> 35</a> 次",
                    "word_list": "",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>hard-working</b> :&nbsp;<span class='suggest'>assiduous</span>",
                    "word_list": "hard-working",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 7,
            "pid": 1,
            "text": "Also be said that God rewards the dilligent.",
            "comment": [
                {
                    "class": "error",
                    "cat": "词语错误",
                    "msg": "请检查<b>dilligent</b>，确认拼写正确。",
                    "word_list": "dilligent",
                    "rank": 100
                }
            ]
        },
        {
            "sid": 8,
            "pid": 1,
            "text": "What's more, every single person is different and we all have kinds of unique talent.",
            "comment": [
                {
                    "class": "great",
                    "cat": "闪光短语",
                    "msg": "<b>what's more</b>有助于提高文章衔接",
                    "word_list": "^ what 's more ,",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "动名搭配 have...kind 在语料库中出现过<a target=\"_blank\" href=\"http://www.pigai.org/corpus/snt/?q=have kind/von\"> 809</a> 次",
                    "word_list": "",
                    "rank": 0
                },
                {
                    "class": "great",
                    "cat": "闪光短语",
                    "msg": "<b>what's more</b>意思是<b>另外，而且…</b>，是经典补充类词组。",
                    "word_list": "what 's more",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 9,
            "pid": 1,
            "text": "There is one more point, some will soar-but many more than previously will not find work to match their talents, qualifications or even quite modest ambitions for a job and a home.",
            "comment": [
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>or</b> :&nbsp;<span class='suggest'>otherwise/if not/before/or else</span>",
                    "word_list": "or",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "推荐表达",
                    "msg": "<b>quite</b> :&nbsp;<span class='suggest'>fairly</span>",
                    "word_list": "quite",
                    "rank": 0
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "动名搭配 match...talent 在语料库中出现过<a target=\"_blank\" href=\"http://www.pigai.org/corpus/snt/?q=match talent/von\"> 17</a> 次",
                    "word_list": "",
                    "rank": 0
                }
            ]
        },
        {
            "sid": 10,
            "pid": 1,
            "text": "Try to find the best way possible to convert your talent to something that gives service to people, Obviously, success always smiles upon people who are diligent.",
            "comment": [
                {
                    "class": "error",
                    "cat": "大小写错误",
                    "msg": "请检查<b>Obviously</b>，疑似大小写错误",
                    "word_list": "Obviously",
                    "rank": 100
                },
                {
                    "class": "error_trp",
                    "cat": "拓展辨析",
                    "msg": "<b>people</b>表示“人，民族”。查看与<a href=\"http://bbs.pigai.org/forum.php?mod=viewthread&tid=12942&page=1&extra=#pid30263\" target=\"_blank\"><b>person</b></a>的区别。",
                    "word_list": "people",
                    "rank": 0
                }
            ]
        }
    ] 
}

6.学生提交作文与同步分析

仅供测试环境，生产环境请使用异步分析

post http://url.com/ding/essaySynchronize?sign=签名

返回体

{
    "error": 0,
    "errorDes": "",
    "data": {
        "dingEssayId": "d-pigai-1234"
        ....#请参考 第5章节的返回
    }
}

7.相似标签

适用于老师作文列表上打相似标签、单篇文章打标签

post http://url.com/ding/similarTag?sign=签名

提交体

{
    "openId":"钉钉用户唯一ID",
    "similar":2000, //大于20% 才相似  这个数字不低于 2000（20%）
    "list":[ //最大数组不超过200
        {
        "dingEssayId":"pigai123",
        "essayVersion":1
        }
        ,{
        "dingEssayId":"pigai124",
        "essayVersion":2
        }
    ]
}

返回体

{
    "error": 0,
    "errorDes": "",
    "data": {
        "list":[
            {
            "dingEssayId":"pigai123",
            "essayVersion":1
            "maxSimilar":0 //未查询到相似
            }
            ,{
            "dingEssayId":"pigai124",
            "essayVersion":2
            "maxSimilar":9812 //相似为98.12%
            }
        ]
    }
}

8.相似详情

这个适用于单篇文章，查看相似详情

post http://url.com/ding/similar?sign=签名

返回体

{
    "error": 0,
    "errorDes": "",
    "data": {
        "dingEssayId": "d-pigai-1234",
        "pigaiEssayId","789"
        "essayVersion":4,
        "similar":{
            "max":9852, //最大相似  整数9852 为 98.5%
            "list":[ //相似列表 会把相似度大于20% 由高到低排序 最多列5条
            {
            "pigaiEssayId":"123", 
            "essayVersion":1,
            "similar":9852,
            "name":"李明",
            "school":"xx大学"
            }
            , 
            {
            "pigaiEssayId":"124", 
            "essayVersion":1,
            "similar":9033,
            "name":"李可",
            "school":"xx大学"
            }
            ],
            "detail":{
                "doc1":{ //原文
                  "pigaiEssayId":"789", 
                  "essayVersion":4, 
                  "name":"李明",
                  "school":"xx大学",
                  "title":"essayTitle",
                  "content":"这里是相似内容用<b>高亮</b>分段使用\n来分段"
                },
                "doc2":{ //相似他文，如果未指定他文 默认是最高的
                  "pigaiEssayId":"123", 
                  "essayVersion":1,
                  "similar":9852,
                  "name":"李明",
                  "school":"xx大学",
                  "title":"essayTitle",
                  "content":"这里是相似内容用<b>高亮</b>分段使用\n来分段"
                }
            }
        }
    }
}

9.异步返回

9.1获取token

参考 https://ding-doc.dingtalk.com/doc#/serverapi2/eev437
ak sk 请更管理员获取

9.2提交返回

post线上：https://oapi.dingtalk.com/topapi/circle/enwork/update

post测试： https://pre-oapi.dingtalk.com/topapi/circle/enwork/update?access_token=c34f610bba4433eaa127e0610e429af2

提交

{
  "open_update_dto": {
    "work_id": "5999065",
    "post_id": "924084530",
    "open_id": "LtR5WtiPcTuAiSiiZWqNVEldQiEiE",
    "similarity": "{}", //相似
    "version_id": 1,
    "pigai_analysis": "{}" //分析结果
  }
}