Что такое код hw_api_object >count

Содержание

Что такое API? Простое объяснение для начинающих

Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. Разработчик Пётр Газаров рассказал об API простыми словами в своём блоге.

Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».

Всемирная паутина и удалённые серверы

WWW можно представить как огромную сеть связанных серверов, на которых и хранится каждая страница. Обычный ноутбук можно превратить в сервер, способный обслуживать целый сайт в сети, а локальные серверы разработчики используют для создания сайтов перед тем, как открыть их для широкого круга пользователей.

При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.

Каждый раз, когда пользователь посещает какую-либо страницу в сети, он взаимодействует с API удалённого сервера. API — это составляющая часть сервера, которая получает запросы и отправляет ответы.

API как способ обслуживания клиентов

Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных.

Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.

Применение API: цель — сервер сайта должен напрямую обращаться к серверу Google с запросом на создание события с указанными деталями, получать ответ Google, обрабатывать его, и передавать соответствующую информацию в браузер, например, сообщение с запросом на подтверждение пользователю.

В качестве альтернативы браузер может сделать запрос к API сервера Google, минуя сервер компании.

Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?

Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.

Если запрос к API делает сервер веб-сайта компании, то он и является клиентом (так же, как клиентом выступает браузер, когда пользователь открывает веб-сайт).

Пользователь благодаря API получает возможность совершить действие, не покидая сайт компании.

Большинство современных сайтов используют по крайней мере несколько сторонних API. Многие задачи уже имеют готовые решения, предлагаемые сторонними разработчиками, будь то библиотека или услуга. Зачастую проще и надёжнее прибегнуть именно к уже готовому решению.

Многие разработчики разносят приложение на несколько серверов, которые взаимодействуют между собой при помощи API. Серверы, которые выполняют вспомогательную функцию по отношению к главному серверу приложения, называются микросервисами.

Таким образом, когда компания предлагает своим пользователям API, это просто означает, что она создала ряд специальных URL, которые в качестве ответа возвращают только данные.

Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:

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

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

  • фрагмент программного обеспечения с определённой функцией,
  • сервер целиком, приложение целиком или же просто отдельную часть приложения.

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой, могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную, внутреннюю логику, которая скрыта от окружения и не является API.

VK API отклоняет запросы наобум, ссылаясь на высокую частоту. Как решить?

Добрейший день. VK API чудит, как не чудил еще никто. В документации написано, что частотное ограничение — 3 запроса в секунду. Пишу на Node.JS. Создал функцию и пакет переменных для контроля частоты обращения с помощью setTimeout, count и тому подобное. Все временные метки, а именно в events: (beforeSend, response), говорят о том, что запросы совершаются ТОЧНО не чаще, чем 3 штуки в 1000 мс, а бывает и того дольше. Но ВК, начиная с 10 запроса из 30 выдает ошибку Too many requests per second (Error code: 6). Бред уже начался. Ок, решил проверить как оно работает «вручную».
Написал функцию send() внутри которой просто функция запроса с колбеком и прочим. Вызвал send 9 раз подряд (внутренние замеры показывают, что отправлялось это дело раз в 1 мс) НИ ОДНОЙ ОШИБКИ, все у VK API хорошо. Ок, я решил выяснить предел — собсна он равен 9. На 10 запросе вк начинает выдавать все ту же ошибку.

Где. Здесь. Логика?! Я уже понял, что VK API делали криворукие, по частоте возвращения ошибок (утром-днем-вечером по 3 ошибки в polling вылетает 100%) 501 502 с текстом «Internal server error: Unknown error, try later», «connect ECONNREFUSED», «Error: socket hang up». Проще говоря, за историю работы с ВК Апи, последний развлекался как мог, самыми разными способами. Но вот чтобы полностью противоречить документации при отсутствии логики в принципе как таковой — это перебор.

Кто может подсказать как быть в такой ситуации или я зря тут гневился и на самом деле я ужасно ступил?

Что такое AMP: подробное руководство по ускоренным мобильным страницам

Время чтения: 24 минуты Нет времени читать? Нет времени?

Ускоренные мобильные страницы или AMP — технология, которая обеспечивает удобное получение информации в интернете с экранов смартфонов и планшетов. Как работает AMP? Как создать и кастомизировать ускоренные мобильные страницы? Какими инструментами могут воспользоваться владельцы сайтов на популярных CMS, включая WordPress, Joomla!, Drupal, OpenCart? С какими подводными камнями сталкиваются вебмастера при внедрении AMP, и как решить проблемы? Ответы на эти и другие вопросы в руководстве.

Что такое AMP и как они работают

AMP — акроним, который образован из первых букв английских слов accelerated mobile pages. По-русски это ускоренные мобильные страницы. Термином обозначают технологию отображения страниц сайта для мобильных пользователей, которая обеспечивает максимальную скорость загрузки сайта.

AMP представляют собой радикально урезанные версии обычных веб-страниц. На ускоренных страницах остается основной контент. Большинство вспомогательных элементов, включая виджеты, формы комментирования, блоки рекомендованного контента, рекламные объявления, на ускоренных страницах отсутствует.

AMP — это платформа с открытым кодом. Поэтому каждый желающий может использовать ускоренные мобильные страницы бесплатно.

Идейным вдохновителем и адвокатом проекта считается Google. Крупнейшая в мире поисковая система использует AMP при формировании страниц поисковой выдачи. Более того, Google кэширует ускоренные страницы сайтов и выступает в роли CDN. Благодаря этому мобильные пользователи быстро загружают AMP даже при низкой скорости передачи данных.

Ускоренные страницы состоят из HTML-разметки со специальными тегами и библиотеки JavaScript. Для создания AMP можно использовать ограниченный набор тегов и скриптов. Это уменьшает функциональность и внешнюю привлекательность страниц, но резко увеличивает скорость их загрузки. Также ускорению загрузки способствует предварительное кэширование.

Серферы могут пользоваться AMP двумя принципиально разными способами. Первый предполагает передачу данных с сервера владельца сайта на компьютер посетителя и отображение в браузере ускоренной версии страницы. Например, на сайте с поддержкой AMP можно настроить автоматическую переадресацию всех мобильных пользователей на ускоренные страницы. Посетитель может попасть на AMP по ссылке с помощью мобильного девайса или добавить к URL в адресной строке браузера на стационарном ПК суффикс /amp/.

Второй способ предполагает просмотр кэшированной версии AMP с сервера Google. Крупнейшая поисковая система мира отображает ссылки на ускоренные страницы в формате карусели в SERP. При просмотре страницы пользователь не переходит на сайт, а просматривает контент со страницы выдачи.

К сожалению, Google не считает нужным показывать AMP-карусели на страницах выдачи, сформированных для моих устройств. Поэтому за пример спасибо Search Engine Land.

В отличие от Google, «Яндекс» не поддерживает технологию AMP.

Пока еще крупнейший поисковик рунета не считает ускоренные мобильные страницы дублями. Это объясняется тем, что AMP ссылаются на канонические страницы с помощью атрибута rel=»canonical».

Тем не менее «Яндекс» индексирует AMP и даже включает их в выдачу. Один из участников популярного SEO-форума рассказал, что поисковик включил ускоренные страницы в выдачу вместо основных. На жалобу техподдержка ответила, что робот не считает атрибут rel=»canonical» строгой директивой. Поэтому AMP оказались в выдаче вместо основных страниц сайта. Топикстартеру пришлось запрещать «Яндексу» индексировать ускоренные страницы в файле robots.txt.

Стоит ли использовать ускоренные мобильные страницы

Чтобы ответить на этот вопрос, нужно уделить внимание преимуществам, недостаткам и результатам внедрения AMP.

Преимущества AMP

Главное преимущество AMP — высокая скорость загрузки. В таблице результаты тестирования базовой и ускоренной версии страницы с помощью нескольких сервисов.

PageSpeed Insights от Google

62 балла для мобильных, 77 баллов для десктопов.

88 баллов для мобильных, 94 балла для десктопов.

Инструмент проверки скорости загрузки от Pingdom

Время загрузки 5,94 секунды, размер страницы 3,5 Мбайт.

Время загрузки 2,46 секунды, размер страницы 381,4 Кбайт.

Инструмент проверки скорости загрузки от GTmetrix

Скорость загрузки 18,6 секунды, размер страницы 3,49 Мбайт.

Время загрузки 3,4 секунды, размер страницы 314 Кбайт.

Ускоренные страницы загружаются в разы быстрее стандартных. Это возможно благодаря значительному уменьшению объема данных с помощью технологии AMP.

Низкая скорость загрузки негативно влияет на пользовательский опыт. Более половины посетителей не ждет отображения контента более 3 секунд.

Быстрая загрузка критически важна для пользователей с мобильными устройствами. Именно поэтому Google предварительно кэширует AMP и выступает в роли CDN для людей, которые пользуются медленным интернетом.

Google учитывает скорость загрузки страниц при ранжировании сайтов. Это важно в контексте тестирования mobile-first индекса. Обеспечивает ли AMP дополнительные преимущества в рейтинге?

В середине 2020 года на саммите Search Engine Journal в Чикаго представитель Google Гарри Ильес заявил, что ускоренные мобильные страницы не входят в число факторов ранжирования. Но специалист не смог однозначно сказать, что AMP не будет фактором ранжирования в будущем.

Что это значит? Технология AMP сама по себе не дает сайтам преимущества при ранжировании. Тем не менее она значительно увеличивает скорость загрузки сайта, которая учитывается при формировании поисковой выдачи.

Новостные сайты и контент-проекты выигрывают от внедрения AMP, если попадают в карусель. Данный элемент отображается в верхней части SERP над результатами поиска. Это обеспечивает сайтам с ускоренными страницами дополнительные переходы.

Итак, основное преимущество ускоренных страниц — высокая скорость загрузки. Она улучшает пользовательский опыт и может опосредованно влиять на позиции сайтов в выдаче Google. Также ресурсы могут получать дополнительные просмотры благодаря карусели AMP.

Недостатки ускоренных мобильных страниц

У AMP много недостатков. Вот основные:

  • Данные о посещении ускоренных страниц не попадают в отчеты «Метрики» и Google Analytics, которые формируются благодаря кодам отслеживания на основных страницах сайта. Чтобы отслеживать эффективность AMP, нужно добавить на них код отслеживания вручную или с помощью плагинов.
  • Ускоренные страницы имеют урезанную функциональность по сравнению с базовыми. На AMP нет навигационного меню, блока похожих публикаций, сайдбара, формы комментирования. Нужные элементы приходится «прикручивать» вручную или с помощью плагинов.
  • Внешний вид AMP отличается от базовых страниц не в лучшую сторону. Ради высокой скорости загрузки вы жертвуете визуальной привлекательностью сайта.
  • На AMP нет сторонних виджетов, например, виджетов групп «Вконтакте» или Facebook.
  • Если Google показывает ускоренные страницы сайта в карусели, пользователи могут читать их, не покидая SERP. Поэтому ваш сайт лишается трафика.
  • Теоретически из-за AMP могут возникать проблемы с индексацией. Пример с «Яндексом» описан выше.

За высокую скорость загрузки приходится платить функциональностью и внешним видом страниц. Стоит отметить, что большую часть недостатков можно полностью или частично устранить. Однако AMP всегда останется упрощенной или даже сокращенной версией базовой страницы сайта.

Результаты внедрения AMP

Сначала личный опыт. Внедрил ускоренные страницы на экспериментальной площадке на WordPress в ноябре 2020 года. Проблем с «Яндексом» нет. Эта поисковая система видит AMP, но не включает их в индекс.

Google быстро индексирует AMP. Информация о них появилась в разделе Search Console «Вид в поиске – Ускоренные мобильные страницы» в течение нескольких дней после внедрения на сайте.

Практически сразу после индексации Google направляет на AMP трафик. По состоянию на конец февраля 2020 года приблизительно каждый третий посетитель из Google попадает на ускоренную, а не на основную версию страницы. Вот интересная статистика:

  • За неделю с 20 по 26 февраля на тестовую площадку из Google пришло 749 посетителей.
  • 397 из 749 человек — мобильные пользователи.
  • 246 пользователей из Google приземлились на ускоренные страницы.

На примере конкретного ресурса без претензии на репрезентативность видно, что Google охотно направляет на AMP посетителей. На ускоренные страницы из поисковой системы пришли 32,84 % от общего числа пользователей или 62 % мобильных пользователей. Оставшиеся 38 % владельцев смартфонов и планшетов попали на базовые страницы с адаптивной версткой.

Вот данные, на которые стоит обратить внимание:

  • За три месяца с момента реализации посетители ускоренных страниц только один раз нажали на объявление AdSense. На ускоренных страницах висит прямоугольный блок 300 на 250 под основным контентом. Другие форматы объявлений пока не тестировал.
  • Показатель отказов AMP значительно выше, чем у стандартных страниц. По данным Google Analytics он достигает 98 %. Это может быть связано с некорректным отслеживанием эффективности ускоренных страниц сервисом Google Analytics. При переходе пользователя с AMP на обычную страницу система мониторинга засчитывает новое посещение. При этом показатель отказов для ускоренных страниц растет, а глубина сессии уменьшается.
  • Показатель просмотренных за сеанс страниц у посетителей AMP ниже чем у посетителей адаптивных страниц. Пользователи намного реже переходят на другие страницы сайта с помощью блока похожих публикаций, чем посетители обычных страниц.
  • На ускоренные страницы практически все пользователи попадают из поисковой системы Google. За неделю Google Analytics зафиксировала несколько посещений с неопределенным источником трафика.
  • Посетители ускоренных страниц редко переходят на полную версию, несмотря на наличие ссылки в футере. За неделю с 20 по 26 февраля сервис аналитики зафиксировал только 10 переходов.

После реализации AMP скачкообразного изменения трафика из Google не было. Сохранилась динамика умеренного роста посещаемости. На посещаемость из «Яндекса» и других источников ускоренные страницы также не повлияли.

Одного ресурса со средней посещаемостью из Google около 100 уников в сутки недостаточно, чтобы оценивать результаты использования AMP. Поэтому стоит обратиться к чужому опыту. Вот интересные данные:

  • По результатам исследования Google заявил о более высокой эффективности контекстной рекламы на AMP по сравнению с обычными страницами. Показы объявлений в видимой части экрана выросли на 80 %, а CTR рекламных блоков выросли на 90 %.
  • Участники известного русскоязычного форума о поисковых технологиях относятся к AMP преимущественно негативно. Вебмастера не замечают изменений трафика. Некоторые специалисты считают, что Google придумал AMP, чтобы лишить сайты трафика. В данном случае речь идет о возможности просмотра контента ускоренных страниц на странице выдачи.
  • Любопытные данные от Search Engine Watch. Журнал Wired благодаря AMP получил рост CTR ссылок в поисковой выдаче на 25 %. А кликабельность объявлений на ускоренных страницах выросла на 63 %. Ежемесячная посещаемость сайта журнала Slate после внедрения AMP выросла на 44 %.
  • Представители CNN в интервью The Wall Street Journal сказали, что AMP и обычные страницы монетизируются с помощью рекламы одинаково эффективно.

AMP загружаются в разы быстрее обычных. За это приходится жертвовать функциональностью и внешним видом страниц. На тестовой площадке резкого роста трафика после внедрения AMP не произошло. Однако Google направляет каждого третьего посетителя в целом из двух из трех мобильных пользователей на ускоренные, а не стандартные страницы тестового блога.

Илон Маск рекомендует:  Faq функция undo в tmemo

Отечественные вебмастера считают AMP ненужным капризом Google, а издатели из англоязычного сегмента Сети сообщают о росте посещаемости сайтов и повышении эффективности объявлений. Эта информация поможет вам самостоятельно решить, стоит ли использовать ускоренные мобильные страницы.

Как установить AMP на WordPress

Пользователям WordPress повезло: ускоренные мобильные страницы можно реализовать буквально в течение минуты. Для этого установите и активируйте плагин AMP.

Созданные с помощью плагина страницы проходят проверку в валидаторе AMP.

Плагин AMP не имеет настроек. Чтобы расширить функциональность и улучшить внешний вид ускоренных страниц, воспользуйтесь надстройкой AMP for WP. После установки и активации плагина перейдите в меню настройки ускоренных страниц в административной панели.

В разделе General при необходимости загрузите логотип сайта. Рекомендованный размер изображения — 190×36. С помощью кнопки Custom Logo Size вы можете указать произвольный размер логотипа.

С помощью кнопки Front Page вы можете указать произвольную страницу в качестве главной на AMP-версии сайта.

Обратите внимание на функцию AMP on Pages. Базовый плагин создает только ускоренные версии страниц записей. Если вам необходимы AMP-версии статических страниц, переключите кнопку в положение On.

В разделе Analytics подключите отслеживание посещений AMP с помощью Google Analytics. Для этого укажите Google Analytics ID.

С помощью кнопки Use Google Tag Manager можно подключить Google Analytics с помощью диспетчера тегов Google.

В разделе Design вы можете изменить внешний вид ускоренных страниц. С помощью кнопки Launch Post Builder запустите drag-and-drop редактор дизайна. Добавляйте и удаляйте элементы страницы, выберите цветовую схему, цвет заголовка и фона.

Меню Design Selector позволяет выбрать готовые варианты дизайна. В поле Custom CSS можно добавить пользовательские стили.

В разделе SEO можно настроить отображение на ускоренных страницах метаданных из плагина Yoast SEO, добавить в хедер произвольный HTML-код, а также настроить индексирование страниц архивов и категорий. Если вы не пользуетесь плагином Yoast SEO, оставьте настройки по умолчанию.

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

В разделе Advertisement настройте отображение объявлений AdSense. Плагин предлагает четыре варианта размещения рекламы: над шапкой на всех страницах, под футером на всех страницах, а также над и под контентом на страницах публикаций.

Чтобы разместить объявление под контентом на страницах публикаций, включите кнопку AD #4. Выберите размер объявления. Создайте объявление в аккаунте AdSense и добавьте идентификаторы пользователя и рекламного блока в предложенные поля. Данные возьмите из кода созданного объявления.

По желанию вы можете показывать на ускоренных страницах блок рекомендуемого контента. Для этого в соответствующем поле плагина укажите идентификатор блока.

Блоки рекомендуемого контента приносят доход при переходах посетителей по рекламным ссылкам, а также стимулируют внутренние переходы на сайте. При выборе размера 300×600 блок выглядит так (см. иллюстрацию).

В разделе Single настройте внешний вид и функциональность страницы записи. Вы можете включить прикрепленные к нижней части экрана социальные иконки, ссылки на предыдущую и следующую публикацию, а также настроить блок похожих записей.

В разделе Social Share подключите кнопки шеринга социальных сетей. В разделе Structured Data загрузите изображение для микроразметки ускоренных страниц. Google может использовать его при формировании поисковой выдачи. Также укажите размер изображений, которые будут использоваться в сниппетах при публикации ссылок на ускоренные страницы в социальных сетях.

В разделе Notification можно настроить отображение уведомлений. Например, вы можете сообщить посетителям об использовании cookies. В разделе Translation Panel переведите меню страниц на русский язык.

В разделе Disqus Comments можно подключить на ускоренных страницах систему комментирования Disqus. Для этого переключите кнопку Disqus Comments Support в положение On, укажите URL ресурса в системе Disqus и путь к файлу комментариев на сервере.

Если вы не подключите систему комментирования, на ускоренной странице будет отображаться текст оставленных посетителями базовой страницы комментариев и кнопка «Комментировать». При нажатии на кнопку пользователь будет перенаправлен на основную версию страницы.

В разделе Advance Settings можно включить ускоренную версию главной страницы, а также страниц рубрик и архивов. За эту функцию отвечают кнопки Homepage Support и Archive Page Support соответственно.

С помощью кнопки Non-AMP Homepage link in Header and Logo можно включить ссылку на полную версию главной страницы в названии сайта и логотипе. Используйте эту возможность, чтобы перенаправлять посетителей ускоренных страниц на базовую версию сайта.

Кнопка Mobile Redirection включает автоматическое перенаправление всех мобильных пользователей с адаптивной версии сайта на AMP.

Не перенаправляйте всех пользователей на AMP. В ускоренных страницах нуждаются не все посетители сайта. Редирект вынудит владельцев смартфонов и планшетов пользоваться сокращенными версиями страниц с ограниченной функциональностью. Это может привести к падению эффективности сайта.

Более того, если Google видит только десктопную версию сайта и AMP, для mobile-first индекса он выбирает версию для стационарных ПК. Это может привести к потере трафика из-за отсутствия адаптации ресурса к мобильным устройствам.

Обязательно включите ссылку на полную версию страниц в футере с помощью кнопки Link to Non-AMP in footer. Это поможет пользователям переходить на базовые страницы с нормальной функциональностью.

В разделе Extension можно приобрести и подключить платные надстройки для плагина. Например, вы можете воспользоваться дополнительным инструментом для управления рекламой на ускоренных страницах или добавить на AMP микроразметку «Рейтинг».

В разделе Fix AMP Errors можно подключить платную поддержку. Разработчики плагина помогут разобраться с настройками и избавиться от уведомлений об ошибках в Search Console.

Блок Import/Export позволяет перенести настройки ускоренных страниц с одного сайта на другой.

Итак, на сайтах под управлением WordPress можно реализовать ускоренные страницы в течение нескольких минут. Чуть больше времени вы потратите на настройку внешнего вида и функциональности с помощью плагина AMP for WP.

AMP для Drupal

Чтобы внедрить ускоренные мобильные страницы на сайтах под управлением Drupal, воспользуйтесь следующими инструментами:

Для работы модуля AMP необходимы плагины Token и Chaos Tools. Если вы планируете показывать на ускоренных страницах объявления AdSense, установите расширение Google AdSense Integration.

На странице настроек модуля AMP на вкладке AMP Configuration подключите отображение ускоренных версий для публикаций и страниц. Выберите тему, которая будет использована для создания AMP. Укажите Google Analytics ID для отслеживания посещений страниц. Также вы можете использовать для учета просмотров AMP-пиксель.

На вкладке AMP Metadata укажите название сайта. При необходимости загрузите логотип и выберите его размер.

После настройки проверьте отображение ускоренных версий страниц. Для этого к URL добавьте значение «?amp». Например, ускоренная версия страницы http://primer-saita.ru/node/1 будет доступна по адресу http://primer-saita.ru/node/1?amp.

AMP для Joomla!

Чтобы внедрить ускоренные страницы на сайтах под управлением CMS Joomla!, воспользуйтесь расширением wbAMP. Полная версия этого плагина обойдется вам в 44 доллара США в год. Сборка для сообщества доступна бесплатно.

После установки и активации плагина перейдите на страницу настроек. Бесплатная версия плагина имеет ограниченную функциональность, поэтому вы сможете настроить только базовые параметры отображения ускоренных страниц.

Оставьте дефолтное значение суффикса для URL AMP. В этом случае для просмотра ускоренных страниц достаточно добавить значение amp. Например, ускоренную версию страницы http://primer-saita.ru/koshki можно будет найти по адресу http://primer-saita.ru/koshki/amp.

Также на странице основных настроек укажите информацию о сайте и данные издателя. Выберите подходящий тип микроразметки: NewsArticle для новостных заметок и BlogPosting для публикаций в блоге.

Выберите страницы, для которых необходимо создавать ускоренные версии. Для этого переключитесь на вкладку «Выбрать страницы».

Заполните раздел «Правило для com_content». Если вы планируете показывать ускоренные страницы только для публикаций, в поле «Представление» укажите значение Article. В поле «Категории» выберите категории, публикации в которых будут иметь AMP-версии. В полях ID, ID номер материала и «Задача» укажите значение «*». В этом случае AMP будут созданы для всех публикаций в выбранных категориях.

Другие настройки в бесплатной версии плагина недоступны.

Существует еще один коммерческий инструмент для создания ускоренных страниц на сайтах под управлением Joomla!: плагин JAmp. Он стоит 39 евро. На тестовом сайте плагина можно увидеть, как инструмент трансформирует стандартную страницу в ускоренную.

В отличие от WordPress и Drupal, для Joomla! нет полностью бесплатного инструмента для создания AMP.

AMP для интернет-магазинов

Технология AMP предназначена в первую очередь для контент-проектов: новостных ресурсов, блогов. Стоит ли создавать ускоренные страницы ecommerce-сайтам?

Авторы проекта AMP утверждают, что онлайн-магазины могут и должны использовать ускоренные страницы. Главный аргумент в пользу внедрения технологии на ecommerce-ресурсах — повышение скорости загрузки мобильных страниц положительно влияет на конверсию. Кстати, eBay экспериментирует с AMP с середины 2020 года.

AMP для OpenCart

Чтобы создать ускоренные страницы для сайта под управлением OpenCart, воспользуйтесь модулем Accelerated Mobile Pages. Это платное решение. Тестовую версию ускоренных мобильных страниц, созданных с помощью модуля, можно посмотреть по ссылке.

Также вы можете испытать модуль AMP for Product Pages. Это бесплатное решение. Надстройка создает AMP только для страниц товаров. Для работы AMP for Product Pages нужен модуль SEO Friendly URLS.

Я не могу рекомендовать бесплатный модуль AMP for Product Pages, так как за полтора рабочих дня не смог заставить его работать на тестовом ресурсе. После установки и активации программы на OpenCart версии 2.3.0.2 ускоренные страницы на сайте не появляются. Надстройка добавляет в хедер страниц ссылку на AMP-версию. При переходе по ссылке появляется ошибка 404.

Кроме того, в результате установки модуля сайт периодически становится недоступным, а на экране браузера появляются кракозябры. Работоспособность восстанавливается после удаления и повторной установки модуля.

Возможно, проблема связана с отсутствием реального опыта администрирования сайтов под управлением ОС OpenCart. Пользователи профильного форума отзываются о модуле AMP for Product Pages преимущественно позитивно.

AMP для Magento

Если ваш интернет-магазин работает на платформе Magento, воспользуйтесь платным плагином Accelerated Mobile Pages. Модуль создает AMP для главной, страниц категорий и товаров.

Демонстрационная версия ускоренных страниц сайта на Magento доступна по ссылке.

AMP для PrestaShop

Ускоренные страницы для магазина на платформе PrestaShop можно создать с помощью платного модуля PrestaShop AMP. Он генерирует ускоренные версии главной, страниц категорий и карточек товаров.

Возможности модуля можно оценить на тестовом сайте.

Внедрять или нет

Если у вас контент-проект, который работает на WordPress, реализовать ускоренные страницы можно быстро и без затрат. Вы потратите минуту на установку базового плагина и полчаса на установку и настройку дополнительного плагина.

Для сайтов под управлением Drupal также есть бесплатное решение, которое можно быстро установить и настроить. А вот для Joomla! и движков для интернет-магазинов плагины для создания AMP придется покупать.

Есть ли смысл использовать AMP, если их функциональность и внешний вид уступают стандартным страницам, а явных преимуществ в ранжировании пока нет?

«Яндекс» не поддерживает технологию и иногда неправильно индексирует ускоренные страницы. Google может передумать и закрыть проект.

Но почему-то кажется, что Google не передумает, а «Яндекс» будет вынужден играть по правилам глобального лидера поискового рынка. Логика простая: доля мобильного трафика растет и будет расти. Люди будут выходить в интернет не только с помощью телефонов и часов. На очереди кофеварки и стиральные машины. Поэтому технологии отображения контента на экранах мобильных устройств будут развиваться.

Кстати, несколько лет назад владельцы сайтов скептически относились к необходимости адаптации сайта под мобильный трафик. Сегодня мобильная версия или адаптивная верстка — обязательное условие эффективной работы онлайн-ресурса. Очень вероятно, что в обозримом будущем технология AMP станет одним из базовых условий эффективности сайтов.

Пишем документацию API при помощи RAML

Удобство работы с любым API во многом зависит от того, как написана и оформлена его документация. Cейчас мы ведём работу по стандартизации и унификации описания всех наших API, и вопросы документирования для нас особенно актуальны.
После долгих поисков мы решили оформлять документацию в формате RAML. Так называется специализированный язык для описания REST API. О его возможностях и преимуществах мы расскажем в этой статье.

Почему RAML

Как нужно документировать API? Вопрос этот не так прост, как может показаться на первый взгляд.
Первый и самый простой вариант, который приходит на ум — представить описание к API в виде обычного текстового документа. Так делают очень многие (в том числе и очень известные компании). Мы тоже не раз пользовались этим способом. При всей своей простоте он обладает следующими недостатками:

  • текстовую документацию сложно поддерживать в актуальном состоянии;
  • зачастую словесные описания API оказываются недостаточно наглядными;
  • сфера использования «словесной» документации очень ограничена (например, на её основе нельзя сгенерировать интерактивную тестовую страницу).

Чтобы упростить процесс документирования, можно использовать специализированные инструменты и сервисы. Как правило, они генерируют документацию на основе описания в некотором стандартизованном формате — обычно это JSON или Markdown.

Ни один из этих форматов для написания документации не подходит. JSОN был изначально создан для обмена данными в вебе. При использовании его для других целей поневоле приходится прибегать к помощи «костылей» — например, кастомных полей, начинающихся со знака $. Кроме того, составлять описания в формате JSON вручную — дело достаточно рутинное и утомительное (в особенности если речь идёт об описаниях большого размера).

На описанные выше трудности обращали внимание многие пользователи популярного инструмента 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 являются:

  • простой и логичный синтаксис, основанный на формате YAML;
  • поддержка наследования и возможность подключения внешних файлов спецификаций.

Дополнительным плюсом является наличие большого количества конвертеров, парсеров и генераторов интерактивной документации. О некоторых из них мы расскажем ниже, а пока перейдём к обзору особенностей синтаксиса RAML.

Краткое введение в RAML

Структура документа

Файл спецификаций на RAML состоит из следующих структурных элементов:

  • вводная часть («шапка»);
  • схема безопасности;
  • описание профилей;
  • описание объектов и методов;
  • описание ответов.

Рассмотрим эти элементы подробнее.

Вводная часть

Каждый документ на RAML начинается с вводной части, которая включает четыре обязательных элемента:

  • версия RAML;
  • имя документа;
  • URI, по которому доступен API;
  • версия API, описываемая в документации.

Выглядит это так:

Вводная часть может также включать различную дополнительную информацию — например, сведения об используемом протоколе для связи с API:

Можно во вводной части прописать и метаданные файла документации:

Схемы безопасности

Чтобы начать работать с любым API, нужно пройти процедуру авторизации. Она может осуществляться разными способами: через OAuth, с помощью токенов, либо посредством простой HTTP-аутентификации. Для описания этой процедуры в RAML используются схемы безопасности (security schemes).
Рассмотрим в качестве примера, как описывается авторизация с использованием протокола OAuth2:

Приведённый фрагмент содержит следующую информацию:

  • в параметре type указывается, что в API используется авторизация по протоколу OAuth2;
  • далее указывается, что авторизационные данные можно передавать либо в заголовке Authorization, либо в query-параметре access_token;
  • после этого следуют возможные коды ответов и их описания;
  • в конце раздела, в секции settings указываются URL для авторизации, URL для получения токена, а также необходимые для аутентификации параметры (authorization grants).

Для удобства схемы безопасности можно сохранять в отдельных файлах .raml или .yml, и затем обращаться к ним в случае необходимости:

Это помогает ускорить процесс документирования, избежать лишних повторений и сделать документацию менее громоздкой.

Почитать более подробно о схемах безопасности и ознакомиться с конкретными примерами можно здесь(раздел Security).

Объекты и методы

Далее перечисляются основные объекты и пути к ним, а также HTTP-методы, которые используются с этими объектами:

В приведённом примере описывается API, с помощью которого можно работать с документами. Мы можем скачивать документы на локальную машину (GET), изменять cуществующие документы (PUT) и загружать новые (POST). С каждым отдельным документом () мы можем также выполнять следующие операции: загрузка на локальную машину (GET) и удаление (DELETE).
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).

Cхемы ответов можно сохранять в отдельных файлах формата .yml или .raml и обращаться к ним в других частях документации:

Визуализация и генерация документации

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 на практике.

Если вы по тем или иным причинам не может оставлять комментарии здесь — добро пожаловать в наш блог.

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

Hyperwave API Функции

Integration with Apache

The integration with Apache and possible other servers is already described in the Hyperwave module which has been the first extension to connect a Hyperwave Server.

> The API prov > HW_API
  • HW_API_Object
  • HW_API_Attribute
  • HW_API_Error
  • HW_API_Content
  • HW_API_Reason
  • Some basic >HW_API_String, HW_API_String_Array, etc., which exist in the Hyperwave SDK have not been implemented since PHP has powerful replacements for them.

    Each > objectIdentifier The name or id of an object, e.g. «rootcollection», «0x873A8768 0x00000002».

  • parentIdentifier The name or id of an object which is considered to be a parent.
  • object An instance of class HW_API_Object.
  • parameters An instance of class HW_API_Object.
  • version The version of an object.
  • mode An integer value determine the way an operation is executed.
  • attributeSelector Any array of strings, each containing a name of an attribute. This is used if you retrieve the object record and want to include certain attributes.
  • objectQuery A query to select certain object out of a list of objects. This is used to reduce the number of objects which was delivered by a function like hw_api->children() or hw_api->find() .
  • Methods returning boolean can return TRUE, FALSE or HW_API_Error object.

    XXXIX. Функции Hyperwave API

    Hyperwave был разработан IICM в Graz. Он начинался как Hyper-G и сменил название на Hyperwave при коммерциализации (насколько помню, это было в 1996).

    Hyperwave это не бесплатная программа. Текущая версия, 5.5, доступна на www.hyperwave.com. Можно запросить оценочную версию с ограниченным временем использования (30 дней).

    Hyperwave это информационная система, аналогичная database (HIS, Hyperwave Information Server). Она сфокусирована на хранении и обслуживании документов. Документом может быть любой блок данных, которые могут сохраняться в файле. Каждый документ сопровождается записью объекта. Запись объекта/object record содержит метаданные документа. Метаданные это список атрибутов, который может быть расширен пользователем. Некоторые атрибуты всегда устанавливаются Hyperwave-сервером, другие могут модифицироваться пользователем.

    С 2001 г. доступен Hyperwave SDK. Он поддерживает Java, JavaScript и C++. Данное расширение PHP базируется на интерфейсе C++. Чтобы активировать поддержку hwapi в PHP, вы должны сначала установить Hyperwave SDK и сконфигурировать PHP с опцией —with-hwapi= .

    API, предоставляемый расширением HW_API, является полностью объектно-ориентированным. Он очень похож на интерфейс C++ Hyperwave SDK. Он состоит из следующих классов.



    Некоторые базовые классы вроде HW_API_String , HW_API_String_Array , etc., которые имеются в Hyperwave SDK, не реализованы, поскольку PHP имеет для них полноценную замену.

    Каждый класс имеет метод, имя которого идентично имени его двойника из Hyperwave SDK. Передача аргументов такой функции отличается от всех других расширений PHP и напоминает C++ API пакета HW SDK. Вместо передачи различных параметров, они все помещаются в ассоциативный массив и передаются как один параметр. Имена ключей идентичны именам, задокументированным в HW SDK. Общие параметры перечислены ниже. Если необходимы другие параметры, они будут документированы, если это необходимо.


    objectIdentifier — имя или id объекта, например, «rootcollection», «0x873A8768 0x00000002».

    parentIdentifier — имя или id объекта, который считается родительским.

    object — экземпляр класса HW_API_Object.

    parameters — экземпляр класса HW_API_Object.

    version — версия объекта.

    mode — целочисленное значение — способ выполнения операции.

    attributeSelector — массив строк, каждая из которых содержит имя атрибута. Это используется, если вы запрашиваете запись объекта и хотите включить некоторые атрибуты.

    objectQuery — запрос на выбор определённого объекта из списка объектов. Используется для уменьшения количества объектов, выдаваемых функциями вроде hw_api->children() или hw_api->find() .

    Интеграция с Apache и, возможно, другими серверами уже описана в модуле Hyperwave Modul, который был первым расширением для соединения с Hyperwave Server.

    Что такое API в веб-приложениях и зачем он нужен

    Начнем с основ: что такое API? Аббревиатура расшифровывается как Application Programming Interface, или интерфейс для программирования приложений. Название, вроде бы, говорит само за себя, но лучше рассмотреть более детальное объяснение.

    Как уже было сказано, API – это, в первую очередь, интерфейс. Интерфейс, который позволяет разработчикам использовать готовые блоки для построения приложения. В случае с разработкой мобильных приложений в роли API может выступать библиотека для работы с «умным домом» – все нюансы реализованы в библиотеке и вы лишь обращаетесь к этому API в своём коде.

    В случае веб-приложений, API может отдавать данные в отличном от стандартного HTML формате, благодаря чему им удобно пользоваться при написании собственных приложений. Сторонние общедоступные API чаще всего отдают данные в одном из двух форматов: XML или JSON. На случай, если вы решили сделать API для своего приложения, запомните, что JSON намного более лаконичен и прост в чтении, чем XML, а сервисы, предоставляющие доступ к данным в XML-формате, постепенно отказываются от последнего.

    API в веб-приложениях на примерах

    Некое приложение – например, Github – имеет свой API, которым могут воспользоваться другие разработчики. То, как они будут пользоваться им зависит от возможностей, которые предоставляет API и от того, насколько хорошо работает фантазия у разработчиков. API Гитхаба позволяет, например, получать информацию о пользователе, его аватаре, читателях, репозиториях и множество других полезных и интересных сведений.

    Если взять, к примеру, API Твиттера, то интерфейс этого сервиса может выдать вам информацию о твитах пользователя, его читателях и о тех, кто его читает, и так далее. Это лишь малая часть возможностей, которые любой желающий может воплотить, используя API стороннего сервиса или создавая свой собственный.

    На основе API строятся такие вещи, как карты 2GIS, всевозможные мобильные и десктопные клиенты для Twitter и Vkontakte. Все их функции стали возможными именно благодаря тому, что соответствующие сервисы имеют качественные и детально документированные API.

    Стандартный запрос данных от стороннего API выглядит примерно так:

    На случай, если кто-то еще не знает, стоит заметить, что curl не имеет никакого отношения к API и используется в операционных системах для отправки и получения данных через терминал. Более подробно на Википедии.

    Подобным образом можно посылать запрос на любом языке, в том числе и на Ruby. Ответом на запрос будет примерно такая информация:

    Как видно из блока выше, ответ содержит логин, аватар, ссылку на профиль на сайте и в API, статус пользователя, количество публичных репозиториев и прочую полезную и интересную информацию.

    Записаться Хочешь узнать ещё больше? Записывайся
    на обучение к нашим менторам

    Зачем нужен API вашему приложению?

    Существует несколько ситуаций, в которых вы можете захотеть создать API для вашего собственного любовно написанного и отрефакторенного приложения.

    Мобильное приложение! Да-да, множество мобильных приложений для различных сервисов работают при использовании API этих самых сервисов. Вы описали API, сделали простенькое мобильное приложение и клиент со смартфоном будет получать информацию в свое устройство именно через API. Это удобно, это разумно, это имеет смысл.

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

    Максимальное разделение фронтенда и бэкенда. Например, при использовании фронтенд-фреймворков. О том, как подключить фронтенд-приложение на Angular.js к API мы даже написали целую статью.

    Одного API недостаточно

    Создать полноценный API для своего приложения – лишь половина дела. Как вы предполагаете обращаться к API? Как к нему будут обращаться ваши пользователи?

    Первое, что приходит в голову, это обычная серия HTTP-запросов с целью получения нужной информации, и это неправильный ответ. Самый очевидный способ в этом случае не является самым удобным и простым. Гораздо разумнее будет создать специальную библиотеку для работы с интерфейсом, в которой будут описаны все необходимые способы получения и отправки информации при помощи API.

    Еще раз воспользуемся Github для приведения примера: для работы с АПИ этого прекрасного сервиса (а интерфейс у него предоставляет обширнейшие возможности) создано несколько библиотек на различных языках, например гем Octokit. В документации к таким библиотекам (и приведенному в качестве примера гему) любой заинтересованный разработчик сможет отыскать все необходимые способы получения информации от Гитхаба и отправки её обратно через API сервиса.

    Таким образом, если вы создаете собственный API, подумайте, возможно стоит озаботиться созданием так же и библиотек для работы с ним на наиболее распространенных языках. И будьте готовы, что при определенном уровне востребованности вашего приложения кто-то другой может создать собственную библиотеку для работы с вашим API. Это нормально.

    Полезные ссылки

    По ссылкам ниже вы сможете прочитать о том, почему API – это хорошо и о том, что такое RESTful API и зачем придерживаться подхода REST.

    В последующих статьях мы расскажем о том, как правильно создавать API, обеспечить его безопасность и ограничить доступ к части информации.

    Мы рассказываем, как стать более лучшим разработчиком, как поддерживать и эффективно применять свои навыки. Информация о вакансиях и акциях эксклюзивно для более чем 8000 подписчиков. Присоединяйся!

    • mkdev
    • Менторы
    • Специализации
    • Статьи
    • О проекте
    • Что такое менторство
    • Как проходит обучение
    • Цены
    • FAQ
    • Impressum
    • Аккаунт
    • Записаться
    • Войти
    • Соцсети

    © Copyright 2014 — 2020 mkdev | Privacy Policy | Lang: Russian

    XXXIX. Функции Hyperwave API

    Hyperwave был разработан IICMв Graz. Он начинался как Hyper-G и сменил название на Hyperwave при коммерциализации (насколько помню, это было в 1996).

    Hyperwave это не бесплатная программа. Текущая версия, 5.5, доступна на www.hyperwave.com. Можно запросить оценочную версию с ограниченным временем использования (30 дней).

    Hyperwave это информационная система, аналогичная database (HIS, Hyperwave Information Server). Она сфокусирована на хранении и обслуживании документов. Документом может быть любой блок данных, которые могут сохраняться в файле. Каждый документ сопровождается записью объекта. Запись объекта/object record содержит метаданные документа. Метаданные это список атрибутов, который может быть расширен пользователем. Некоторые атрибуты всегда устанавливаются Hyperwave-сервером, другие могут модифицироваться пользователем.

    С 2001 г. доступен Hyperwave SDK. Он поддерживает Java, JavaScript и C++. Данное расширение PHP базируется на интерфейсе C++. Чтобы активировать поддержку hwapi в PHP, вы должны сначала установить Hyperwave SDK и сконфигурировать PHP с опцией —with-hwapi= .

    API, предоставляемый расширением HW_API, является полностью объектно-ориентированным. Он очень похож на интерфейс C++ Hyperwave SDK. Он состоит из следующих классов.



    Некоторые базовые классы вроде HW_API_String , HW_API_String_Array , etc., которые имеются в Hyperwave SDK, не реализованы, поскольку PHP имеет для них полноценную замену.

    Каждый класс имеет метод, имя которого идентично имени его двойника из Hyperwave SDK. Передача аргументов такой функции отличается от всех других расширений PHP и напоминает C++ API пакета HW SDK. Вместо передачи различных параметров, они все помещаются в ассоциативный массив и передаются как один параметр. Имена ключей идентичны именам, задокументированным в HW SDK. Общие параметры перечислены ниже. Если необходимы другие параметры, они будут документированы, если это необходимо.


    objectIdentifier Имя или id объекта, например, «rootcollection», «0x873A8768 0x00000002».

    parentIdentifier Имя или id объекта, который считается родительским.

    object Экземпляр класса HW_API_Object.

    parameters Экземпляр класса HW_API_Object.

    version Версия объектанн.

    mode Целочисленное значение — способ выполнения операции.

    attributeSelector Массив строк, каждая из которых содержит имя атрибута. Это используется, если вы запрашиваете запись объекта и хотите включить некоторые атрибуты.

    objectQuery Запрос на выбор определённого объекта из списка объектов. Используется для уменьшения количества объектов, выдаваемых функциями вроде hw_api->children() или hw_api->find() .

    Интеграция с Apache и, возможно, другими серверами уже описана в модуле Hyperwave Modul, который был первым расширением для соединения с Hyperwave Server.

    Что такое код hw_api_object >count

    1.2
    Кнопка инж. меню только для mtk
    Улучшено определение устройств

    1.3
    Улучшено определение устройств rockchip и qualcom

    1.5
    Вкладки
    Для mtk на 2 вкладке инфа из ProjectConfig.mk
    Разметка rockchip и mt6752 (берет из /proc/partinfo)
    Адреса устройств i2c (вкл. в настройках)

    1.6 Upload test
    Разметка теперь и на mt6589 и др.
    Определение чипа wifi на rockchip.
    Исправление ошибок
    В тестовом режиме загрузка характеристик в БД

    1.7
    Улучшено определение устройств по данным БД
    Базовая поддержка samsung
    Обновлен сайт и форма загрузки данных

    1.8
    Определение камер на платформе qualcom (требуется root)
    Определение датчиков через Android API (если не нашли)
    На mt6735+ показываем только активные камеры
    Подписи вкладок

    1.9
    + Добавлена возможность обновить базу определения компонентов из программы (в меню about)
    Правила определения устройств вынесены в отдельный файл git components
    + Улучшено определение устройств
    + При изменении настроек, они сразу применяются

    2.0 (release candidate 3)

    rc1
    Добавлена новая вкладка с информацией:
    — CPU (Кол-во ядер, семейство, частота, говернор)
    — GPU (модель, частота, версия OpenGL)
    — Память

    Начальная поддержка CPU из нескольких кластеров.

    На qcom root запрашивает только, если включен в настройках. (Для определения моделей камер)

    rc2
    Релизная версия, добавил свою подпись для приложения

    rc3
    Повышена стабильность
    На mtk вкладка config показывается только при наличии файла

    2.1
    Фикс загрузки инфы (upload)
    версия java vm

    1) Добавлены новые вкладки:

    1. Система
    2. Память (озу, диски, пути монтирования)
    3. Камера
    аппаратные характеристики: пытаюсь определить производителя, разрешение
    программные характеристики: через Android API (для android P20 / P20 series / P25 / P25 series

    — Обновлены компоненты обнаружения.
    — ZTE, BQ qcom: пробуем определить камеры (на sd820 есть).
    — Новый метод определения компонентов для устройств с 7.0/7.1, где запрещено чтение sysfs (qcom, hisi).

    — Обновлены компоненты обнаружения. Улучшено определение компонентов для 7.0/7.1
    — Для некоторых устройств добавлен размер ПЗУ.
    — Исправление ошибок.

    — Обновлены компоненты обнаружения.
    — Улучшена поддержка Galaxy S9 (exynos9810, sdm845)
    — qcom: улучшено определение поддерживаемых камер
    (для новых устройств msm8996/sdm6xx на конце ‘_cust’ для наиболее вероятных)
    — qcom: для определения имен разделов не требуется root (для устройств на 5.1 и др).
    — Исправление ошибок.

    — Обновлены компоненты обнаружения.
    — Исправлен детектор компонентов для sdm6xx на 7.x
    — Названия разделов для mt65xx на 4.4
    — Обнаружение датчика отпечатка по spi
    — Пробное обнаружение wi-fi, ethernet для amlogic и др.
    — Исправлено зависание при вкл. root на M6 Note
    — Определение камер на некоторых устройствах OnePlus
    — Исправлены ошибки

    — Обновлены компоненты обнаружения.
    — qcom: Новый метод определения камер (не требует root)
    Должен работать на 5,6 и 7.0+ где не заблокировано чтение.
    — Определение кол-ва ядер mali gpu для некоторых устройств
    — mt6763: теперь должны определиться все камеры
    — Дополнительная инфа о камере (программно)
    — Исправление ошибок

    — Обновлены компоненты обнаружения.
    — qcom: Новый метод определения камер с root для 7.x/8.x
    — mtk: Новый метод определения дисплея для ядер 3.18
    На 6.0 и большинстве 7.0 без root
    — exynos: Новый метод определения частоты gpu, чипа ufs для новых моделей (проверено на galaxy s9+)
    — Улучшено определение ЦП для rockchip, amlogic
    — Исправлено определение kirin 970
    — Исправление ошибок

    — Обновлены компоненты обнаружения.
    — Определение устройств ввода теперь и для 8.x
    — Для 7.1 и ниже список монтирования разделов. На вкладке разметка нажать на заголовок.
    На новых можно увидеть схему system a/b
    — Для 7.x/8.x с root доступно больше информации
    — Для 7.x/8.x добавлен экспериментальный детектор компонентов.
    Для qcom:
    — Новый метод определения частоты gpu без root на 7.x/8.x sdmXXX
    — Улучшен метод определения модели батареи
    — Новый метод определения поддерживаемых камер для sdmXXX
    — Исправление ошибок

    Версия 4.14.x 280818

    — Определение поддерживаемых камер для sdm845
    — При активации camera2 api доступны значение апертуры и iso.
    — Для mtk 7.0+ у кого заблокировано чтение поддерживаемых камер, можно скопировать библиотеку libcameracustom.so в папку программы, будет считывать оттуда.

    Версия 4.15.x 041018

    — Обновлены компоненты обнаружения экспер. детектора для 7.x/8.x без root. По результатам тех, кто заливал в базу.
    — Если включен root на 7.0+ вернется вкладка драйверы (но будут все, не только активные, с root слишком медленно)
    — Для Spreadtrum 7.0+ у кого заблокировано чтение поддерживаемых камер, можно скопировать библиотеку camera.PLATFORM.so (sc8830 и др.) в папку программы, будет считывать оттуда.
    — Исправление ошибок
    [PRO]
    Улучшен отчет:
    — Добавлена инфа c вкладок устройства ввода и wi-fi
    — Добавлена кнопка отправить, позволяет отправить отчет на почту (в виде файла)
    — В низу приписывается, какой версией программы был создан отчет
    — Исправлена кодировка, заголовок страницы

    Версия 4.16.x 051118
    — Обновлены компоненты обнаружения
    — Улучшена поддержка памяти для новых cpu
    — Добавлена вкладка кодеки
    — На 8.x Определение звуковой карты без root (qcom, hisi)
    — kirin980 определение архитектуры

    Версия 4.17.x 011218
    — galaxy s9 sdm845 дисплей, поддерживаемые камеры
    — Для Qualcomm добавлено определение названия датчиков температуры, требуется root и включить в настройках эту функцию.
    У меня, например, заменяет tsens_tz_sensor12 на gpu, и 5 датчиков для cpu.

    Версия 4.18.x 17012020

    — Обновлены компоненты обнаружения
    — HiSi: определение дисплея с root kirin960+
    — HiSi: определение типа дисплея oled/amoled или ips/lcd
    — HiSi: поддерживаемые камеры kirin970+
    — sdm845: Определение дисплея для lg, xiaomi где не заблокировано.
    — Начато улучшение определения компонентов для x86 ноутбуков
    [PRO]
    — HiSi: определение модели камеры по данным из фото (exif).
    В меню инфо-центр выбрать фото, покажет инфу. Можно выделить и скопировать данные.

    Версия 4.19 04032020

    — Обновлены компоненты обнаружения
    — Улучшено определение snapdragon 855, exynos9820, Helio P70
    — kirin970+ определение поддерживаемых камер
    — Исправление ошибок

    Версия 4.20 29032020

    Улучшена поддержка snapdragon 855, 712, 675; exynos9820, Helio P70

    Новая версия 4.21 27052020 — 27062020

    — Обновлены компоненты обнаружения
    — На вкладке система, теперь выпуск android (соответствует API) Бывают фейковые версии android прописывают.
    — Для xiaomi sdm855 c root, у кого определялось 2 камеры из 4, должны все показываться.
    — Попытался немного оптимизировать
    — sdm730

    — Улучшено определение устройств для android 9.
    — Snapdragon 855+, 665. Добавлен Кэш L3 для ЦП
    — Добавлены характеристики камеры camera 2 api:
    Размер пикселя (у кого неправильное разрешение, то на полученное значение не смотрите)
    Угол обзора (горизонтальный)
    Цветовой фильтр (Color Filter Arrangment)

    — Обновление до sdk28, также в списке приложений добавлена версия sdk.
    — На 8.0+ (у кого недоступна разметка), вместо нее пути монтирования (+добавлен размер).
    kirin
    Новый метод для определения дисплея с root для kirin970+
    Тестовый метод определения производителя дисплея huawei mate 20 pro, где старый заблокирован на emui 9.1
    mtk
    Поддерживаемые камеры для новый устройств (проверено на 9.0 mt6771)
    qcom
    Поддерживаемые камеры, исправлен метод для msm8996 — sdm6xx на 8.0+

    — Исправлены ошибки, исправлена работа на Redmi K20 Pro

    Сообщение отредактировал ANDR7E — 08.11.19, 13:03

    DATA API

    Соглашения

    Приняты следующие соглашения при использовании Data API:

    • Пустые поля всегда возвращаются в ответе со значением null . В случае массива возвращается пустой массив, в случае объекта возвращается пустой объект;
    • Все поля связанные с датой и временем передаются в формате YYYY-MM-DD hh:mm:ss;
    • Запросы к API выполняются всегда с помощью метода POST;
    • Все параметры в запросах/ответах, а также в структурах данных в формате JSON и название методов именуются в стиле Snake Case — разделение слов через нижнее подчёркивание;
    • Данные возвращаются только в JSON формате согласно спецификации RFC 7159. Заголовок Accept игнорируется;
    • Кодировка данных UTF-8;
    • Заголовок Content-Type должен быть «application/json; charset=UTF-8» ;
    • Заголовок Content-Length должен содержать корректную длину сообщения, следуя спецификации HTTP/1.1

    Добавить IP-адрес в список разрешенных

    По умолчанию доступ к API запрещен всем, чтобы можно было делать запросы необходимо IP-адрес хоста с которого делается запрос добавить в белый список. Это можно сделать через личный кабинет «Администратор -> Аккаунт -> Правила и настройки безопасности» вкладка «API».

    Если необходимо разрешить доступ всем IP-адресам, то нужно добавить в список разрешенных 0.0.0.0/0

    Если запрос делается из под агента, то его IP адрес должен быть добавлен в белый список клиентского аккаунта

    Пользователи API и аутентификация

    К пользователям и ключам доступа применяются права доступа аналогичные правам доступа в личном кабинете

    Доступ по ключу

    Ключи генерируются на уровне пользователя в разделе личного кабинета «Аккаунт» → «Управление пользователями»
    Существует два типа ключей:

    Постоянный ключ имеет неограниченное время действия.
    Временный ключ имеет конкретную дату окончания действия ключа.

    Доступ по логину и паролю

    Используется аутентификация с использованием сессий

    Отчёт по запросам к API

    В личном кабинете «Отчёты»->»Служебные»->»Запросы к API» можно построить отчёт по запросам к API

    Базовый URL для доступа к API

    Базовый URL для доступа к API соответствует следующему шаблону:

    — https;

  • — api.comagic.ru, api.uiscom.ru;
  • — версия API (см. раздел Версионность)
  • Версионность

    Текущая версия Data API 2.0

    Data API поддерживает версионность. Версия указывается в базовом URL как vX.Y , где X — номер мажорной версии, Y — номер минорной версии

    Если была выпущена новая версия, то старая считается устаревшей и соответственно при обращении к старой версии API в мета-параметрах (см. раздел Мета-параметры) будет возвращаться параметр «current_version_deprecated» со значением «true»

    Максимальное количество поддерживаемых версий — 2
    Период поддержки устаревшей версии 2 месяца

    Лимиты и ограничения

    Баллы списываются только за успешные запросы, т.е в отчете по запросам к API (см. раздел Отчёт по запросам к API) он помечен как успешный.

    Информация о лимитах возвращается во всех ответах в мета-парметрах (см. раздел Мета-параметры) кроме случаев когда лимиты не учитываются;

    Лимиты построены по бальной системе, т.е каждый метод имеет свой вес. Вызов метода уменьшает доступные дневные/минутные баллы на размер веса вызываемого метода

    Информация о лимитах в мета-параметрах:

    Название параметра Описание
    day_limit Текущий лимит баллов в день
    day_remaining Какое количество баллов осталось до достижения дневного лимита
    day_reset Время в секундах через которое дневной лимит будет сброшен
    minute_limit Текущий лимит баллов за минуту
    minute_remaining Какое количество баллов осталось до достижения минутного лимита
    minute_reset Время в секундах через которое минутный лимит будет сброшен

    Методы и их стоимость в баллах

    Тип операции Стоимость в баллах
    Все операции 1

    Расширение лимитов

    На странице «Аккаунт» -> «Тарифы и опции» в личном кабинете можно расширить лимиты.

    Обработка ошибок

    Параметры сообщения об ошибке

    Название Тип Обязательный Описание
    error object да Объект с содержимым ошибки
    code number да Не уникальный код ошибки (см. раздел Группы кодов ошибок )
    message string да Cообщение об ошибке
    data object да Объект с деталями ошибки
    mnemonic string да Уникальный текстовый код ошибки. При обработке ошибок рекомендуется использовать этот параметр.
    value string нет Содержит то, что передал пользователь без изменений

    В некоторых случаях может отсутствовать. К примеру, обязательный параметр вообще не был заполнен.

    extended_helper string нет Ссылка на более подробное описание ошибки и возможные решения params object нет Карта подстановок параметров для шаблона с текстом об ошибке. Т.е. содержит динамически изменяемые значения, к примеру, лимиты. Значения указанные в этом параметре могут быть использованы в сообщениях об ошибках в интерфейсе, который базируется на Data API. field string нет Название параметра, с которым связана ошибка

    Вложенные параметры отображаются через разделитель точка «.»
    К примеру: «employee.phone_number»

    JSON структура ошибки

    Группы кодов ошибок

    Код ошибки Описание
    -32700 Ошибки связанные с валидацией JSON
    -32600 Ошибки связанные с валидацией параметров запроса — id , jsonrpc
    -32601 Ошибки связанные с методом
    -32602 Ошибки связанные с валидацией параметров в вызываемом методе
    -32603 Внутренние ошибки JSON RPC сервера
    -32001 Ошибки аутентификации и ошибки с ключами
    -32003 Ошибки с правами доступа — ip адрес не в белом списке, нет прав у пользователя
    -32004 Ошибки связанные с неверной последовательностью вызываемых методов
    -32007 Ошибки связанные с виртуальным номером
    -32008 Ошибки связанные с компонентами
    -32009 Ошибки связанные с аккаунтом
    -32029 Ошибки связанные с лимитами
    -32099 Ошибки связанные с поддержкой различных частей спецификации JSON RPC 2.0 — Групповые операции, Уведомления

    Список ошибок общих для всех методов

    Текст сообщение Код Мнемоника Описание
    Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Ошибки связанные с валидацией параметров запроса — id , jsonrpc
    Access token has been expired -32001 access_token_expired Применяется только к постоянному токену. Если время жизни постоянного токена истекло, то возвращается указанная ошибка
    Access token has been blocked -32001 access_token_blocked Если постоянный токен заблокирован, то возвращается указанная ошибка
    Access token is invalid -32001 access_token_invalid Указанная ошибка возвращается если постоянный/временный токен не найден
    Limit per has been exceeded. Value of current limit per is -32029 limit_exceeded Лимит превышен
    You need at least on of the following components to access this method: -32008 method_component_disabled Если не подключен компонент, который требуется для работы метода
    You need at least on of the following components to access this paremeter: -32008 parameter_component_disabled Если не подключен компонент, который нужен для заполнения параметра и создания сущности
    Your IP is not whitelisted -32003 ip_not_whitelisted IP адрес с которого делается запрос не находится в белом списке адресов. Если запрос делается из под агента, то ваш IP адрес должен быть в списках разрешеных адресов внутри клиентского аккаунта
    Login or password is wrong -32001 auth_error Неправильный логин или пароль
    Your account has been disabled, contact the support service -32009 account_inactive Аккаунт заблокирован
    Internal error, contact the support service -32603 internal_error Внутренняя ошибка, необходимо обратиться в службу технической поддержки
    Data supplied is of wrong type -32602 data_type_error К примеру, если ожидаем string а передали int
    The method does not exist / is not available -32601 method_not_found Вызываемый метод не найден
    Permission denied -32003 forbidden Нет прав на доступ к методу или API, или запрещено выполнять какое-либо действие
    Invalid JSON was received by the server. -32700 parse_error Ошибка валидации JSON
    Batch operations not supported -32099 batch_opreations_not_supported Групповые операции не поддерживаются
    Notifications not supported -32099 notifications_not_supported Был потерян параметр id в запросе. См. раздел Общие параметры для всех методов»
    The required parameter has been missed -32602 required_parameter_missed Обязательный параметр не передали
    Invalid parameter value -32602 invalid_parameter_value Возвращается во всех случаях, если было передано некорректное значение параметра или переданное значение не соответствует требуемому формату ввода
    Unexpected method parameter(s) -32602 unexpected_parameters Если в «params» были переданы параметры которые не предусмотрены JSON структурой метода или указан параметр для сортировки, фильтрации и выборки, который не существует
    The combination of parameters is not permitted -32602 invalid_parameters_combination Если параметры указанные в методе находятся в недопустимой комбинации или имеют зависмость друг от друга. Нужно смотреть документацию по методу и его параметрам.
    -32602 error Динамические ошибки

    Список ошибок для методов с глаголом get

    Текст ошибки Код Мнемоника Описание
    Invalid parameter value -32602 invalid_parameter_value Если в фильтрах было передано некорректное значение для regexp, jsquery или любых значений не соответствующих документации
    Sort by parameter is prohibited -32602 sort_prohibited Сортировка по параметру запрещена и невозможна, так как параметр для сортировки не находится в списке разрешенных для сортировки
    Filter by parameter is prohibited -32602 filter_prohibited Фильтрация по параметру запрещена и невозможна, так как параметр для фильтрации не находится в списке разрешенных для фильтрации
    Max value of requested date interval is 3 months -32602 date_interval_limit_reached Если в запросе период между указанными датами в date_from и date_till превышает 3 месяца. В основном ошибка актуальна только для методов получения отчетов, но не для всех.

    Список ошибок общих для методов с глаголом delete

    Текст ошибки Код Мнемоника Описание
    Entity not found -32602 entity_not_found Если передан уникальный идентификатор сущности, которая не найдена
    You have interdependet entities -32602 dependency_error Удаляемая сущность используется в других сущностях. Чтобы удалить, необходимо убрать удаляемую сущность из всех возможных мест где она используется
    Permission denied -32602 forbidden Удалить сущность невозможно так как она системная, к примеру группа «Черный список» в адресной книге

    Список ошибок общих для методов с глаголом create и update, set, unset

    Текст ошибки Код Мнемоника Описание
    Entity not found -32602 entity_not_found Если передан уникальный идентификатор сущности, которая не найдена
    Duplicate entity -32602 duplicate_entity Если сущность уже существует
    A new data limit has been exceeded -32602 data_limit_exceeded Ошибка возникает в случае, если было достигнуто максимальное количество данных.
    Action is not allowed for your tariff plan. You need contact support service or change your tariff plan settings in your account -32602 tariff_restrictions Любые ограничения тарифного плана
    This value is already used by another entity -32602 already_in_use Значение указанного параметра уже используется в другой сущности. К примеру, виртуальный номер уже используется в другой рекламной кампании.

    Групповые операции

    Функционал не поддерживается

    Принцип именования методов

    Имя JSON-RPC метода состоит из двух частей разделенных точкой: глагола и имени объекта.

    Имя объекта выбирается как существительное во множественном числе, отражающее бизнес-сущность, например subscribers .

    Имя метода должно начинаться с глагола, отражающего суть операции.

    Глаголы используемые в именовании методов

    Глагол Описание
    create Добавляет сущность.
    get Возвращает список отсортированных и отфильтрованных данных с помощью критериев фильтрации и методов сортировки. К запросу возможно применить лимит и постраничный вывод на количество получаемых данных (см. раздел Постраничный вывод). С помощью критериев фильтрации может быть так же получена одна запись, по ёё уникальному идентификатору (см. раздел Критерии фильтрации). В специальном мета-параметре возвращается общее количество записей (см. раздел Мета-параметры). С помощью специального параметра можно указать какие поля возвращать в ответном сообщении (см. раздел Представление возвращаемых данных).
    update Обновляет сущность с определённым идентификатором.

    Возможно частичное обновление параметров
    При обновлении массивов обновляется весь массив целиком, т.е все элементы которые не были переданы удаляются.
    Для зануления необязательного параметра нужно передать null

    delete Удаляет сущность с определённым идентификатором. add Связь одного объекта с другим. enable Подключение объекта disable Отключение объекта set Простановка свойства на другой объект, к примеру, установка тега на обращение unset Снятие свойства с другого объека, к примеру, снятие тега с обращения

    Критерии фильтрации

    Фильтрация данных применяется только к глаголу «get» (см. раздел «Глаголы используемые в именовании методов» с помощью необязательного примитива «filter» , который является объектом и может содержать:

    1. Простой фильтр;
    2. Дерево фильтров которое содержит простые фильтры с условиями.

    Простой фильтр — это объект, который содержит в себе обязательные примитивы:

    • field — поле сущности к которой будет применяться фильтрация (список заранее определён для метода);
    • operator — оператор фильтрации. Список всех операторов можно получить в разделе «Операторы фильтрации»;
    • value — значение для оператора фильтрации. Необязательное поле, если оно отсутствует, то считается пустота.

    Дерево фильтров содержит специальный примитив «filters» , который может содержать в себе как простые фильтры, так и дерево фильтров.

    Возможные ошибки при фильтрации

    Текст Код Мнемоника Описание
    Filter by parameter is prohibited -32602 filter_prohibited Фильтрация по параметру запрещена и невозможна, так как параметр для фильтрации не находится в списке разрешенных для фильтрации
    Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

    Пример JSON структуры простого фильтра

    Получаем список записей у которых поле «name» имеет имя «Bob»

    Пример JSON структуры дерева фильтров с одним уровнем вложенности

    Получаем список записей у которых поле «name» имеет имя «Bob» и его возраст 25 лет

    Пример JSON структуры дерева фильтров с двойным уровнем вложенности

    Получаем список записей у которых поле «name» имеет имя «Bob» и его возраст 25 лет или список записей у которых поле «name» имеет имя «Dexter» и его возраст 2 года

    Пример JSON структуры дерева фильтров с тройным уровнем вложенности

    Условие запроса ((addv_comp_ >

    Операторы фильтрации

    Фильтрация null и not null будет =null, !=null

    Оператор Описание Учёт регистра строк Тип данных
    = Равно да number, string, null, boolean, iso8601, enum
    != Не равно да number, string, null, boolean, iso8601, enum
    Меньше чем number, iso8601
    > Больше чем number, iso8601
    Меньше или равно number, iso8601
    >= Больше или равно number, iso8601
    like Начинается с, Заканчивается на, Содержит
    да string regexp Posix да string jsquery PostgreSQL jsquery да object, array in Массив значений в отношении «or» да number, string, enum

    Сортировка данных

    Сортировка данных применяется только к глаголу «get» (см. раздел «Глаголы используемые в именовании методов») с помощью массива объектов сортировки со следующими примитивами:

    • field — поле по которому производится сортировка;
    • order — направления сортировки. Возможные значения «asc» / «desc» . «asc» — по возрастанию, «desc» — по убыванию. Параметр необязателен. Значение по умолчанию «asс» .

    Список полей по которым можно производить сортировку определяется индивидуально для каждого метода.

    Возможные ошибки при сортировки

    Текст ошибки Код Мнемоника Описание
    Sort by parameter is prohibited -32602 sort_prohibited Сортировка по параметру запрещена и невозможна, так как параметр для сортировки не находится в списке разрешенных для сортировки
    Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

    Постраничный вывод

    Постраничный вывод может быть применён к глаголу «get» (см. раздел «Глаголы используемые в именовании методов»). Для выполнения пагинации данных используются следующие параметры:

    Параметр Значение по умолчанию Допустимое значение Описание
    offset 100 000 Сдвиг, определяет с какого номера записи возвращать «limit» записей
    limit 1000 10 000 Размер возвращаемых данных (количество записей)

    Мета-параметры

    Возвращаются при использовании глагола «get» (см. раздел «Глаголы используемые в именовании методов»).

    Присутствуют как в ошибочном, так и в успешном ответе

    Параметр «api_version» возвращается только для версий которые deprecated.

    Представление возвращаемых данных

    Отдельный список возвращаемых столбцов

    В глаголе получения данных «get» (см. раздел «Глаголы используемые в именовании методов») может быть указан специальный необязательный примитив «fields» с типом массив, который может содержать список полей которые необходимо показать в выводе. Если примитив «fields» не используется, то в выводе показываются все поля по умолчанию для вызываемого метода.

    Список полей индивидуален для каждого метода.

    Возможные ошибки в представлении возвращаемых данных

    Текст Код Мнемоника Описание
    Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

    Общие поля для всех методов

    Название Тип Обязательный Допустимые значения Описание
    id string или number да Уникальный идентификатор запроса к API, который используется для связи запроса с ответом. Рекомендуется делать в виде уникального хэша или случайного числа .
    method string да Вызываемый метод
    jsonrpc string да 2.0 Номер спецификации JSON-RPC
    params object да Содержит тело запроса к API. В зависимости от вызываемого метода тело запроса меняется.

    Аутентификация

    Метод login.user
    Описание Вход и получение ключа сессии аутентификации
    Кому доступен Партнёр, Клиент

    Параметры запроса

    Название Тип Обязательный Допустимые значения Описание
    login string да Логин пользователя
    password string да Пароль пользователя

    Параметры ответа

    Название Тип Обязательный Описание
    access_token string да Ключ сессии аутентификации
    expire_at number да Timestamp когда выданный токен перестанет быть валидным
    app_id number да Уникальный идентификатор клиента

    Время жизни полученного ключа сессии аутентификации после вызова метода «login.user» — 1 час. По истечению времени жизни ключа сессии его необходимо запрашивать заново, т.е. вызывать метод «login.user» .

    Для совершения запросов к API возможно использование постоянного ключа аутентификации, который доступен в Личном кабинете на уровне пользователя.

    Понравилась статья? Поделиться с друзьями:
    Кодинг, CSS и SQL