Статьи

Новая функция API Collaborator – Часть 1

 Это первая часть технической серии статей о новой функции 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 .