Это первая часть технической серии статей о новой функции Collaborator API.
У Collaborator совершенно новый API, и я хотел посмотреть, что я могу с ним сделать. Но что было бы полезно? Какая польза от этого, кроме как для меня научиться?
Несколько парней из офиса упомянули, возможно, создание надстройки для Microsoft Word. Я подслушал, и вскоре после этого я отправился на гонки. Я знал достаточно об архитектуре Microsoft Word, чтобы быть опасным, так как я написал несколько плагинов Office в прошлой жизни. Это будет легко! Или это было?
Перед тем, как создать плагин Word, мне нужно было знать, что к этому относится точнее, мне нужно было знать, как отправлять запросы в новый API Collaborator . Помимо просто отправки запроса, мне нужно было понять механизм аутентификации и мне нужно было знать, как отправлять соответствующие команды для создания обзора с приложенным документом. Это также потребовало, чтобы я получил документ из своей локальной копии Word в Collaborator, что означало его загрузку.
Но как мне отправить файл на этот новый веб-сервис?
Вот история моего путешествия и создания простого подключаемого модуля Office, вращающегося вокруг Collaborator JSON / RPC API.
История начинается с JSON. Что это? Это аббревиатура для JavaScript Object Notation. Как это реализовано? Ну, это не так просто.
Прочитав документацию по API, я узнал, что Collaborator принимает запросы HTTP POST в / services / json / v1. Запрос должен быть списком команд в паре с аргументами для каждого.
[ {"command" : "ServerInfoService.getVersion" }, {"command" : "Examples.echo", "args" : {"echo" : "Some text."} }, ]
Затем сервер вернет список объектов ответа, которые соответствуют запросам. Каждый объект ответа является либо сообщением об ошибке, либо данными результата из команды запроса.
[ { "result" : { "version" : "9.1.9100" } }, { "result" : { "echo" : "Some text." } }, ]
Теоретически, это звучит достаточно просто, но для его реализации нужно немного подумать. Какой самый простой способ создать строку запроса JSON? Какой самый простой способ обработать ответ JSON с сервера?
Я мог бы просто построить строки вручную, подставив соответствующие значения для переменных, но этого оказалось недостаточно. Это не было достаточно просто для поддержки, и это будет подвержено ошибкам. Мне нужно что-то лучше.
Ответ был довольно прост: сериализация JSON. Практически все современные языки предоставляют этот механизм тем или иным способом, либо нативно, либо с помощью библиотек с открытым исходным кодом или коммерчески доступных. JavaScript поддерживает его изначально, но вы не можете написать плагин Word на JavaScript, это должен быть C #. Microsoft предоставляет пространство имен System.Runtime.Serialization.Json как часть .NET Framework, которая может сделать это. Однако его немного сложно использовать, поэтому я решил использовать стороннюю библиотеку Json.NET от Newtonsoft.
С Json.NET я мог взять ванильный класс C #, создать его экземпляр, а затем легко превратить его в строку JSON.
public class JsonRequest { string command; List args; }
JsonRequest myRequest = new JsonRequest(); myRequest.command = "ServerInfoService.getVersion"; string json = JsonConvert.SerializeObject(myRequest);
Полученная строка JSON была именно тем, что мне было нужно:
{ "command" : "ServerInfoService.getVersion" }
Инвертировать этот процесс было бы одинаково просто, если бы у меня была строковая переменная, полная JSON:
string json = "{'command' : 'ServerInfoService.getVersion'}";
Затем я мог бы превратить его в объект JSONRequest, например так:
JsonRequest myRequest = JsonConvert.DeserializeObject<JsonRequest>;
Просто! Затем я обнаружил бы, что объект MyRequest имеет значение команды, равное «ServerInfoService.getVersion».
Это стало бы одним из основополагающих строительных блоков плагина. Возможность предопределения моего контракта на данные в виде классов .NET обеспечила гибкость и простоту, которые мне были нужны. Это простое и элегантное решение, которое легко расширить.
В следующей части мы углубимся в то, как вы запускаете сериализованные JsonRequests в действие. Вы можете увидеть это в действии на GitHub .