Query параметры что это
Пишем документацию API при помощи RAML
Удобство работы с любым API во многом зависит от того, как написана и оформлена его документация. Cейчас мы ведём работу по стандартизации и унификации описания всех наших API, и вопросы документирования для нас особенно актуальны.
После долгих поисков мы решили оформлять документацию в формате RAML. Так называется специализированный язык для описания REST API. О его возможностях и преимуществах мы расскажем в этой статье.
Почему RAML
Как нужно документировать API? Вопрос этот не так прост, как может показаться на первый взгляд.
Первый и самый простой вариант, который приходит на ум — представить описание к API в виде обычного текстового документа. Так делают очень многие (в том числе и очень известные компании). Мы тоже не раз пользовались этим способом. При всей своей простоте он обладает следующими недостатками:
На описанные выше трудности обращали внимание многие пользователи популярного инструмента Swagger. Вскоре разработчики Swagger решили упростить работу по написанию спецификаций и создали фирменный редактор с поддержкой формата YAML.
Конечно, YAML гораздо удобнее, чем JSON. Но и его использование сопряжено с определёнными трудностями. Дело в том, что в описаниях API всегда имеются повторяющиеся элементы (например, схема ответа, которая может быть одинаковой для разных типов HTTP-запросов), которые приходится всякий раз прописывать вручную. Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости… Но, увы, пока что такой возможности нет.
Что касается формата Markdown (он используется, например, в API BluePrint), то предназначен в первую очередь для оформления текста, а не для использования в качестве основы для генерирования. Приспособить его под документирование API очень сложно. По этой же причине не привели к каким-либо заметным результатам попытки cоздать формат описания API на базе XML — например, язык WADL (Web Application Desription Language), разработанный компанией Sun Microsystems ещё в 2009 году, но так и не получивший широкого распространения.
Создатели проекта RAML (эта аббревиатура означает RESTful API Modeling Language — язык для моделирования REST API ) предприняли попытку разработать язык, предназначенный исключительно для описания API и исправить недочёты, свойственные другим форматам. Первая версия спецификации RAML была опубликована в 2013 году. Основным разработчиком RAML является компания MuleSoft; в проекте также принимают участие представители таких известных компаний, как Cisco, PayPal, ВoxInc. и других.
Краткое введение в RAML
Структура документа
Файл спецификаций на RAML состоит из следующих структурных элементов:
Вводная часть
Каждый документ на RAML начинается с вводной части, которая включает четыре обязательных элемента:
Вводная часть может также включать различную дополнительную информацию — например, сведения об используемом протоколе для связи с API:
Можно во вводной части прописать и метаданные файла документации:
Схемы безопасности
Чтобы начать работать с любым API, нужно пройти процедуру авторизации. Она может осуществляться разными способами: через OAuth, с помощью токенов, либо посредством простой HTTP-аутентификации. Для описания этой процедуры в RAML используются схемы безопасности (security schemes).
Рассмотрим в качестве примера, как описывается авторизация с использованием протокола OAuth2:
Приведённый фрагмент содержит следующую информацию:
Это помогает ускорить процесс документирования, избежать лишних повторений и сделать документацию менее громоздкой.
Почитать более подробно о схемах безопасности и ознакомиться с конкретными примерами можно здесь(раздел Security).
Объекты и методы
Далее перечисляются основные объекты и пути к ним, а также HTTP-методы, которые используются с этими объектами:
В приведённом примере описывается API, с помощью которого можно работать с документами. Мы можем скачивать документы на локальную машину (GET), изменять cуществующие документы (PUT) и загружать новые (POST). С каждым отдельным документом (
HTTP-заголовки, используемые с тем или иным методом, описываются при помощи свойства headers, например:
Обратите внимание на свойство required: оно указывает, является ли заголовок обязательным (true) или необязательным (false).
В описании объектов и методов могут использоваться многочисленные дополнительные параметры. Рассмотрим следующий пример:
Здесь мы указываем, что каждый из документов, доступ к которым можно получить через API, имеет собственный идентификационный код в виде строки (type: string), а также описываем формат этого кода с помощью регулярных выражений.
Свойства description, type и pattern можно использовать и в описаниях методов, например:
В описании метода POST мы указываем параметры, которые нужно передать в теле запроса для добавления нового документа: ID, имя и имя автора. Каждый из этих параметров является строкой (type: string). Обратите внимание на свойство required: оно указывает, является ли параметр обязательным (true) или необязательным (false).
Для каждого метода можно прописать индивидуальную схему безопасности:
Query-параметры
Для каждого метода в документации можно указать query-параметры, которые будут использоваться в запросе. Для каждого query-параметра указываются следующие характеристики: имя, тип, описание и пример:
Профили
Чтобы избежать лишних повторений в описаниях, в RAML используются профили (traits), которые прописываются во вводной части документа:
В дальнейшем к профилю можно обращаться при описании любых методов:
Более подробно о профилях и особенностях их использования можно почитать в официальной документации (раздел Traits).
Описание ответа
В описании ответа обязательно указывается его код. Также в описание можно добавить схему (schema) — перечисление входящих в ответ параметров и их типов. Можно также привести пример конкретного ответа (example).
Визуализация и генерация документации
RAML2HTML и другие конвертеры
Несмотря на то, что RAML — формат относительно новый, для него уже разработано достаточное количество конвертеров и парсеров. В качестве примера можно привести ram2htmtl, генерирующий на основе описания в формате RAML статическую HTML-страницу.
Устанавливается он при помощи менеджера пакетов npm:
Чтобы сконвертировать RAML-файл в HTML, достаточно выполнить простую команду:
Поддерживается возможность создания собственных шаблонов для HTML-файлов (подробнее об этом см. в документации на GitHub по ссылке выше).
Из других конвертеров рекомендуем также обратить внимание на RAML2Wiki и RAML2Swagger.
API Designer
Компания Mulesoft (один из активных участников проекта RAML) создала специальный онлайн-инструмент, с помощью которого можно упростить работу по написанию документации и последующему тестированию API. Называется он API Designer.
Чтобы начать им пользоваться, нужно сначала зарегистрироваться на сайте. После этого можно приступать к работе. API designer предоставляет, во-первых, удобный интерактивный редактор для написания документации онлайн, а во-вторых — платформу для тестирования.
Выглядит всё это так:
В правой части страницы автоматически генерируется интерактивная документация. Здесь же можно и протестировать API: для этого достаточно просто развернуть описание нужного запроса и нажать на кнопку Try it.
API Designer позволяет также загружать RAML-файлы с локальной машины. Поддерживается импорт файлов описаний API для Swagger.
Кроме того, API Designer хранит статистику тестовыx запросов к API.
API console
API console — полезный инструмент, разработанный всё той же компанией MuleSoft. С его помощью можно прямо в браузере генерировать документацию к API. Файлы спецификаций можно как загрузить с локальной машины, так и указать ссылку на внешний источник:
В состав API Console входит несколько файлов-образцов, представляющих собой описания API популярных веб-сервисов: Twitter, Instagram, Box.Com, LinkedIn. Мы попробовали сгенерировать на основе одного из низ документацию — выглядит вполне симпатично:
Документация, получаемая на выходе, является интерактивной: в ней можно не только прочитать описание API, но и выполнить тестовые запросы.
Заключение
В этой статье мы рассмотрели основные возможности RAML. Его несомненными преимуществами являются простота и логичность. Надеемся, что в скором будущем RAML получить ещё более широкое распространение и займёт достойное место в ряду инструментов для документирования API.
Если у вас есть вопросы — добро пожаловать в комментарии. Будем также рады, если вы поделитесь собственным опытом использования RAML на практике.
Если вы по тем или иным причинам не может оставлять комментарии здесь — добро пожаловать в наш блог.
QUERY. Функция для создания запросов в Google-Таблицах
Спасибо Евгению Намоконову за помощь в подготовке материала.
Функция QUERY позволяет сделать выборку нужных строк из таблицы с помощью SQL-запроса и отсортировать их.
=QUERY(данные; запрос; [заголовки])
Итак, правила формирования запросов:
Рассмотрим несколько примеров применения QUERY на практике.
Простой пример: выбираем книги определенной тематики из таблицы
Из простой исходной таблицы будем формировать список книг по тематике:
При этом тематику будем выбирать из выпадающего списка на отдельном листе:
Функция QUERY для решения этой задачи будет выглядеть следующим образом:
Мы извлекаем данные из столбцов A и C в диапазоне ‘Книги’!A1:C. Фильтруем данные по столбцу B (тематике) этого диапазона по выбранному критерию из выпадающего списка в ячейке A1. Сортируем по убыванию по столбцу C исходного диапазона и добавляем к нашей выборке заголовки (последний аргумент функции QUERY = 1).
Группируем данные с помощью GROUP BY и PIVOT
Сгруппировать данные, используя QUERY, можно с помощью двух ключевых слов: GROUP BY и PIVOT, ниже рассмотрим примеры с ними.
Таблица, с которой мы будем работать:
Задачей будет вывести сумму продаж по каждой тематике, то есть сгруппировать данные по столбцу B.
Начнем с GROUP BY, текст функции будет таким:
=QUERY(‘Книги‘!A1:C6;»select B, sum(C) group by B»)
Обратите внимание: чтобы функция работала, помимо группировки (group by B) нужна хотя бы одна аггрегирующая функция, в нашем случае это sum(C). Напишу, на всякий случай, все аггрегирующие функции для QUERY: sum(), max(), min(), avg() и count().
Результат нашей формулы:
С помощью GROUP BY возможна группировка и по нескольким столбцам, для этого просто перечислите их, как в функции ниже и не забудьте добавить эти столбцы в SELECT: 
Группировка с помощью PIVOT.
Обратите внимание, что здесь в SELECT не нужно писать столбец B, по которому данные будут сгруппированы.
Пока отличие в том, что сгрупированные элементы расположены по столбцам, а не по строкам, как в GROUP BY.
Добавим еще один столбец для группировки.
Строим сводную таблицу со средними/максимальными значениями по тематикам
В этом примере мы построим небольшую сводную таблицу, где будут отображены средние значения по тематикам за два года:
Мы используем похожий диапазон (в отличие от предыдущего в нем есть продажи за 2015 и 2016 годы), извлекаем средние значения по столбцам C и D (SELECT avg(C), avg(D)) и группируем их по столбцу B (тематика).
Полученный результат транспонируем для удобного отображения (с помощью функции TRANSPOSE (ТРАНСП)):
Можно использовать и другие функции вместо avg (среднего), например max (максимальные значения):
Или отобразить и среднее, и максимум, но только по столбцу D:
Кейс «Считаем средний чек, выбирая данные с определенной даты»
На скриншоте массив данных, с которым мы будем работать:
Наша задача: отобрать строки с продажами начиная с 1 апреля и посчитать по ним средний чек, используя количество клиентов, то есть получить среднее взвешенное.
Начнем. Создадим QUERY с умножением количества клиентов (столбец B) на средний чек (столбец С) начиная с определенной даты:
Правильно использовать дату в формуле QUERY так:
Вернемся к тому, что у нас получилось. Наша формула выдала вот такой массив данных:
Это построчные произведения количества клиентов на средний чек. Нам нужно просуммировать их, для этого введем перед формулой СУММ (SUM):
Чтобы получить средний чек, получившееся число нужно разделить на общую сумму клиентов в отобранных строках. Чтобы закрепить использование QUERY, опять воспользуемся этой формулой.
Берем предыдущую формулу, меняем B*C на sum(B) и получаем такую конструкцию:
Наконец, совмещаем формулы:
Все работает, ура! 53 (этот результат видно на всплывающей подсказке в верхнем левом углу) — средний чек с учетом количества клиентов, рассчитанный через среднее взвешенное.
Кейс «QUERY и выпадающий список»
Возьмем табличку с продажами книг. На ее основе будем делать отчет с выпадающим списком, в котором будут все тематики, и формулой QUERY, выводящей книги выбранной тематики и сортирующей их по продажам.
Итак, выпадающий список. Вначале создадим новый лист (допустим, наша исходная таблица огромна, и всю аналитику мы хотим производить на другом листе). Кликаем правой кнопкой мыши на ячейку А1, выбираем Проверка данных.
В Правилах выбираем Значение из списка, перечисляем все наши тематики через запятую и нажимаем Сохранить:
Список получился вот таким:
В соседнюю ячейку А2 впишем следующую формулу:
И разберем ее по частям:
Изменив тематику в ячейке А1 на философию, мы получим книги только по философии, отсортированные по продажам. Удобно.
Если бы в нашей исходной таблице была дата, мы могли бы добавить ее в условие QUERY и выводить данные за выбранный день, месяц, неделю — таким образом можно получить готовый отчет по продажам, который не нужно каждый раз заново собирать.
Query по нескольким диапазонам данных
В качестве первого аргумента функции QUERY можно указать массив, состоящий из нескольких диапазонов данных. Главное, чтобы эти диапазоны были таблицами с одинаковой структурой.
Диапазоны указываются через точку с запятой в фигурных скобках:
Спасибо Евгению Намоконову за помощь в подготовке кейсов для этой статьи. Мы с Евгением ведем канал в Телеграме по Google Таблицам.
Регулярно публикуем новые кейсы и советы. Заглядывайте в гости:
Параметры URL-запроса в отчетах Google Analytics и инструмент для их извлечения
Специалисты, работающие с Google Analytics, видели или знают, что в отчетах с параметром “Страница” (Page) одна и та же страница может дублироваться за счет добавления разных параметров.
В этой статье я расскажу, откуда берутся эти параметры, почему их наличие может мешать, а главное — что с ними делать.
Что такое параметры запроса URL
Параметры запроса URL (URL Query Parameters) — это дополнительная информация, которую можно добавить в URL-адрес. Состоит из двух обязательных элементов: из самого параметра и его значения, разделенных знаком равенства (=).
Параметры указываются в конце URL, отделяясь от основного адреса знаком вопроса (?). Можно указать более одного параметра, для этого каждый параметр со значениями отделяется от следующего знаком амперсанда (&).
Виды параметров
Есть параметры, которые влияют на страницу, к URL-адресу которой они добавлены.
И есть параметры, никак не влияющие на страницу, к URL-адресу которой они добавлены. Их обычно используются для передачи какой-то информации о посещении сайта.
Как посмотреть параметры запросов
Чтобы увидеть все параметры запросов, с которыми взаимодействовали пользователи на сайте, в Google Analytics надо:
На многих сайтах можно увидеть большое количество страниц с разными параметрами.
Что плохого в параметрах запросов
Основная причина, по которой наличие большого количества параметров —плохо, это “размытие” данных о странице.
Посмотрите на отчет ниже. Это данные по взаимодействию с главной страницей и её параметрами за последние 6 месяцев.
В нижнем правом углу показано количество строк в отчете. Более 55 тысяч уникальных параметров, на которые приходится около 20% от всех просмотров главной страницы.
При этом, если сравнить выведенные метрики качества основной главной страницы (/) и главной страницы с параметрами, мы видим существенные отличия.
То есть неконтролируемые параметры могут сильно искажать данные о странице.
Что делать с параметрами
Самое просто решение — исключать их из отчетов Google Analytics. При этом исключаются не сами взаимодействия, а удаляются параметры из URL-адресов страниц, “приклеивая” оставшуюся информацию к основной странице. То есть, если в отчете есть информация о 10 взаимодействиях с основной страницей и информация о 10 взаимодействиях с параметрами этой страницы, после исключения параметров мы получим 20 взаимодействий с основной страницей.
Google Analytics по умолчанию сам умеет исключать параметры (_ga, UTM-метки). Для исключения других параметров в Google Analytics есть удобный встроенный инструмент исключения параметров запросов URL. Находится он в разделе “Администратор > Представление > Настройки представления”.
Достаточно указать в данном поле через запятую все параметры, которые надо исключать из отчетов, и в момент внесения изменений данные в представлении будут отображаться без параметров.
Тут стоит сделать две важные ремарки:
Какие параметры запросов исключать
Из отчетов надо исключать параметры второго вида, то есть те, которые не влияют на работу сайта, но передают дополнительные параметры.
Но перед удалением параметров обязательно надо обсудить с командой проекта, не связан ли какой-нибудь отчет с этими параметрами.
Ниже пример параметров, которые мы обычно исключаем:
Без предварительной подготовки из отчетов не рекомендуется исключать параметры, которые влияют на работу сайта: пагинация, фильтрация, сортировка, действия пользователей. Так как эти параметры могут служить хорошим источником информации для разных исследований и гипотез. Например, какие фильтры с какими значениями предпочитают выбирать пользователи из разных рекламных кампаний.
Отойду от темы и скажу, что часть информации из параметров лучше отправлять в пользовательские параметры. Но это тема отдельной статьи.
Инструмент сбора параметров URL запроса
Раньше для сбора параметров из отчетов Google Analytics необходимо было выгрузить данные из отчетов, выделить параметры, подчистить их, проанализировать.
Но коллеги из 3whitehats разработали инструмент “Google Analytics Query Parameter Extractor”, который позволяет автоматизировать весь процесс, сведя его к нескольким простым шагам. Сам инструмент работает на базе Google Таблиц + расширения Google Analytics Spreadsheet Add-on.
Как пользоваться инструментом:
Все настройки проводятся на первом листе “Query Parameter Extractor”.
Данные в полях с датами необходимо указывать в формате YYYY-MM-DD.
Может потребоваться авторизация скрипта.
В поле ниже будут собраны все найденные параметры, а в круговой диаграмме – частота появления этих параметров.
Надеюсь, эта статья поможет вам внести ясность в тему параметров URL-запросов, а инструмент позволит обрабатывать эти параметры эффективнее и быстрее.
Пишем документацию API при помощи RAML
Почему RAML
Как нужно документировать API? Вопрос этот не так прост, как может показаться на первый взгляд.
Первый и самый простой вариант, который приходит на ум — представить описание к API в виде обычного текстового документа. Так делают очень многие (в том числе и очень известные компании). Мы тоже не раз пользовались этим способом. При всей своей простоте он обладает следующими недостатками:
Чтобы упростить процесс документирования, можно использовать специализированные инструменты и сервисы. Как правило, они генерируют документацию на основе описания в некотором стандартизованном формате — обычно это JSON или Markdown.
Конечно, YAML гораздо удобнее, чем JSON. Но и его использование сопряжено с определёнными трудностями. Дело в том, что в описаниях API всегда имеются повторяющиеся элементы (например, схема ответа, которая может быть одинаковой для разных типов HTTP-запросов), которые приходится всякий раз прописывать вручную. Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости…. Но, увы, пока что такой возможности нет.
Что касается формата Markdown (он используется, например, в API BluePrint ), то предназначен в первую очередь для оформления текста, а не для использования в качестве основы для генерирования. Приспособить его под документирование API очень сложно. По этой же причине не привели к каким-либо заметным результатам попытки cоздать формат описания API на базе XML — например, язык WADL (Web Application Desription Language), разработанный компанией Sun Microsystems ещё в 2009 году, но так и не получивший широкого распространения.
Создатели проекта RAML (эта аббревиатура означает RESTful API Modeling Language — язык для моделирования REST API ) предприняли попытку разработать язык, предназначенный исключительно для описания API и исправить недочёты, свойственные другим форматам. Первая версия спецификации RAML была опубликована в 2013 году. Основным разработчиком RAML является компания MuleSoft; в проекте также принимают участие представители таких известных компаний, как Cisco, PayPal, ВoxInc. и других.
Несомненными преимуществами RAML являются:
Дополнительным плюсом является наличие большого количества конвертеров, парсеров и генераторов интерактивной документации. О некоторых из них мы расскажем ниже, а пока перейдём к обзору особенностей синтаксиса RAML.
Краткое введение в RAML
Структура документа
Файл спецификаций на RAML состоит из следующих структурных элементов:
Рассмотрим эти элементы подробнее.
Вводная часть
Каждый документ на RAML начинается с вводной части, которая включает четыре обязательных элемента:
Вводная часть может также включать различную дополнительную информацию — например, сведения об используемом протоколе для связи с API:
Можно во вводной части прописать и метаданные файла документации:
Схемы безопасности
Чтобы начать работать с любым API, нужно пройти процедуру авторизации. Она может осуществляться разными способами: через OAuth, с помощью токенов, либо посредством простой HTTP-аутентификации. Для описания этой процедуры в RAML используются схемы безопасности (security schemes).
Рассмотрим в качестве примера, как описывается авторизация с использованием протокола OAuth2:
Приведённый фрагмент содержит следующую информацию:
Это помогает ускорить процесс документирования, избежать лишних повторений и сделать документацию менее громоздкой.
Почитать более подробно о схемах безопасности и ознакомиться с конкретными примерами можно здесь (раздел Security).
Объекты и методы
Далее перечисляются основные объекты и пути к ним, а также HTTP-методы, которые используются с этими объектами:
В приведённом примере описывается API, с помощью которого можно работать с документами. Мы можем скачивать документы на локальную машину (GET), изменять cуществующие документы (PUT) и загружать новые (POST). С каждым отдельным документом (
HTTP-заголовки, используемые с тем или иным методом, описываются при помощи свойства headers, например:
Обратите внимание на свойство required: оно указывает, является ли заголовок обязательным (true) или необязательным (false).
В описании объектов и методов могут использоваться многочисленные дополнительные параметры. Рассмотрим следующий пример:
Здесь мы указываем, что каждый из документов, доступ к которым можно получить через API, имеет собственный идентификационный код в виде строки (type: string), а также описываем формат этого кода с помощью регулярных выражений.
Свойства description, type и pattern можно использовать и в описаниях методов, например:
В описании метода POST мы указываем параметры, которые нужно передать в теле запроса для добавления нового документа: ID, имя и имя автора. Каждый из этих параметров является строкой (type: string). Обратите внимание на свойство required: оно указывает, является ли параметр обязательным (true) или необязательным (false).
Для каждого метода можно прописать индивидуальную схему безопасности:
Query-параметры
Для каждого метода в документации можно указать query-параметры, которые будут использоваться в запросе. Для каждого query-параметра указываются следующие характеристики: имя, тип, описание и пример:
Профили
Чтобы избежать лишних повторений в описаниях, в RAML используются профили (traits), которые прописываются во вводной части документа:
В дальнейшем к профилю можно обращаться при описании любых методов:
Более подробно о профилях и особенностях их использования можно почитать в официальной документации (раздел Traits).
Описание ответа
В описании ответа обязательно указывается его код. Также в описание можно добавить схему (schema) — перечисление входящих в ответ параметров и их типов. Можно также привести пример конкретного ответа (example).
Визуализация и генерация документации
RAML2HTML и другие конвертеры
Чтобы сконвертировать RAML-файл в HTML, достаточно выполнить простую команду:
API Designer
В правой части страницы автоматически генерируется интерактивная документация. Здесь же можно и протестировать API: для этого достаточно просто развернуть описание нужного запроса и нажать на кнопку Try it.
API Designer позволяет также загружать RAML-файлы с локальной машины. Поддерживается импорт файлов описаний API для Swagger.
Кроме того, API Designer хранит статистику тестовыx запросов к API.
API console
API console — полезный инструмент, разработанный всё той же компанией MuleSoft. С его помощью можно прямо в браузере генерировать документацию к API. Файлы спецификаций можно как загрузить с локальной машины, так и указать ссылку на внешний источник:
В состав API Console входит несколько файлов-образцов, представляющих собой описания API популярных веб-сервисов: Twitter, Instagram, Box.Com, LinkedIn. Мы попробовали сгенерировать на основе одного из низ документацию — выглядит вполне симпатично:
Документация, получаемая на выходе, является интерактивной: в ней можно не только прочитать описание API, но и выполнить тестовые запросы.
Заключение
В этой статье мы рассмотрели основные возможности RAML. Его несомненными преимуществами являются простота и логичность. Надеемся, что в скором будущем RAML получить ещё более широкое распространение и займёт достойное место в ряду инструментов для документирования API.
Если у вас есть вопросы — добро пожаловать в комментарии. Будем также рады, если вы поделитесь собственным опытом использования RAML на практике.