Синтаксис REST API на примере Excel Services и SharePoint 2010

Спасибо Кристиану Стич (Christian Stich) за составление серии публикаций о REST API.

В предыдущей заметке мы видели как просто пользьвоваться REST API в Excel Services. Достаточно определить URI (Uniform Resource Identifier) для отображения в веб-браузере. В этой заметке мы приведем детали синтаксиса URI.

Мы начнем с простой книги Excel, хранящихся на сервере SharePoint 2010 по следующему адресу:

https://contoso/Finance/Shared%20Documents/Tax.xlsx

В этом примее книга содержит два именованных диапазона, диаграмму, таблицу и сводную таблицу.

Для того, чтобы создать URI, который будет использоваться для доступа REST API, мы вставим _vti_bin/ExcelRest.aspx/ в URL, который приведен выше (в нашем примере после /Finance).

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx

Работа с элементами книги

Теперь добавим /Model после имени файла (в нашем примере после /Tax.xlsx)

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model

Теперь у нас есть URI, который может использоваться, чтобы достать элементы из книги - REST API возвращает ATOM feed содержащий типы элементов доступных, в настоящее время - диапазонов, графиков, таблиц и сводных таблиц.

Примечание: Если книга находится в корне сайта на сервере SharePoint то _vti_bin /ExcelRest.aspx/ нужно вставить после имени сервера.

ДО:

https://contoso/Shared%20Documents/Tax.xlsx

ПОСЛЕ:

https://contoso/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model

Получение элементов книги

Мы можем получить список именованных диапазонов простым добавлением диапазонов к URI. Или вы можете нажать на ссылку диапазона, который был возвращен в предыдущем примере.

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges

REST API возвращает Atom feed, который содержит именованные диапазоны книги - эта книга содержит два именованных диапазона: TaxRate и Revenue.

Так же мы можем получить HTML представление диапозона, указав:

/Ranges(‘range name’) and by adding ?$format=HTML.

Чтобы получить HTML представление именованного диапазона Revenue зададим следующий URI:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Revenue’)?$format=HTML

Доступ к таблицам, сводным таблицам и графикам похож на доступ к диапазону, как показано выше.

Таблицы:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Tables

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Tables(‘RevenueTable’)?$format=html

Сводные таблицы:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/PivotTables

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/PivotTables(‘PivotTable’)?$format=html

Графики:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=image

Поддерживаемые форматы REST API

Обратите внимание на предыдущий пример. Мы добавили параметр запроса к строке URI. Используя этот параметр REST API должен возвращать значение определенного формата. В настоящее время поддерживаются следующие форматы:

• html
• atom
• image
• workbook

?$format=html означает, что REST API вернёт представление в HTML, кторое может быть отображено в веб-браузере.

?$format=atom означает, что REST API вернёт представление как ATOM feed.

?$format=image означает, что REST API вернёт картинку (на данный момент только в формате PNG).

Я расскажу больше о том, что возвращает ?$format=atom, в следующем посте посвященному REST API. В нем же я расскажу про отличия ATOM feeds для /Ranges, /Tables и /PivotTables

?$format=workbook означает, что REST API вернёт книгу, которая может быть открыта в Excel или сохранена на диск. Возвращаемый формат книги соответствует формату оригинального файла. Если исходный файл в формате .XLSX то и формат возвращаемой книги тоже будет.XLSX. Если исходный формат.Xlsb, то и возвращаемый формат тоже будет.xlsb. То же самое касается и.Xlsm формата.

Какой формат каким запросом поддерживается?

Не все форматы поддерживаются различными элементами. Кроме того, для разных типов запросов REST API используются различные значения по умолчанию. Например /Charts(‘chart name’) по умолчанию вернет картинку. Это означанет, что вам не нужно писать ?$format=image в URI. Так же можно опустить ?$format=html в случае использования /Ranges(‘range name’).

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)

эквивалентно

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=image

Оба URI возвращают картинку в формате PNG.

Ниже приведена матрица, которая показывает, поддерживаемые форматы для разных запросов REST API.

Произвольные диапазоны.

В приведенном выше примере было показано, как получить доступ к именованным диапазонам. Помимо этого можно получить доступ к произвольному диапазону (без названия) используя обозначения ячеек. Следующий URI, демонстриурет, как получить доступ к одной ячейке диапазона, а так же к диапазону ячеек.

Чтобы получить значение ячейки A1 на Листе1 (Sheet1) используйте следующий URI:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Sheet1!A1’)?$format=HTML

Чтобы получить значение диапазона A1:D4 на Листе2 используйте следующий URI:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Sheet2!A1|D4’)?$format=HTML

ПРИМЕЧАНИЕ: Вы должны заменить привычное двоеточие в обозначени диапазона. В REST API, для указания диапазона используется символ линии (pipe) диапазон A1:D4 вводится как А1 | D4

Вставка данных

Excel Services REST API предоставляет средства для изменения значений в книге. Эти изменения влияют только на значения, которые возвращает REST API в виде, HTML или графиков, в данном конкретном запросе. Эти изменения не сохраняются в книге. Они так же не затрагивают другие REST API запросы или веб-сесси с Excel.

Изменять значения ячеек просто. Для этого нужно определить ячейку, диапазон ячеек или именованный диапазон.

Рассмотрим следующий пример. Возмем книгу, в которой имеется именованный диапазон с именем "Tax Rate" (Ставка налога), который в настоящее время ровняется 10%.

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)

в результате получим диаграмму.

Изменим в книге Ставку Налога до 50% добавив ?Ranges(‘TaxRate’)=0.50

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50

результатом станет обновленная таблица:

Мы также могли бы использовать обозначение ячейки, например A1, чтобы указать ячейку, которая должна быть изменена (именованный диапазон ‘TaxRate’, в нашем примере, равнялся бы ‘Sheet1!B1’)

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘Sheet1!B1’)=0.50

Кроме того, можно установить несколько значений в разных ячейках. Дополнительные параметры отделяют амперсандом - &.

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50&Ranges(‘FiscalYear’)=2008

Вы можете совмещать все это с указанием возвращаемого формата - порядок параметров в запросе не имеет значения. Например:

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50&Ranges(‘FiscalYear’)=2008&$format=html

и

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘FiscalYear’)=2008&$format=html&Ranges(‘TaxRate’)=0.50

и

https://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=html&Ranges(‘FiscalYear’)=2008&Ranges(‘TaxRate’)=0.50

являются эквивалентными и возвращают один и тот же результат.

Еще не все

На этом рассмотрение синтаксиса REST API заканчивается. Теперь у вас должно быть достаточно знаний, чтобы начать построение REST-решений на базе Excel Services. В моем следующем посте я продемонстрирую несколько простых сценариев, которые вы сможете реализовать самостоятельно.

Перевел - Михаил Даньшин, https://danshin.ms