Что не является графическим api: Что не является графическим API

Знакомство с графовыми API / Блог компании Издательский дом «Питер» / Хабр

Привет, Хабр! Мы не перестаем отслеживать тему проектирования API после того, как встретили в портфеле издательства «Manning» вот эту книгу. Сегодня мы решили опубликовать обзорную статью об относительно новых Graph API и предлагаем еще раз задуматься о том, каковы будут новые API после безраздельной популярности REST.

Приятного чтения!

Если в последние 10 лет вам доводилось потреблять API – готов поспорить, что это был REST API. Вероятно, данные были структурированы вокруг ресурсов, в отклики включались id, указывающие на связанные объекты, а при помощи HTTP-команд сообщалось, как поступить с информацией: прочитать, записать и обновить (да, согласен, это вольное определение, а не канонический REST Роя Филдинга). Некоторое время API в стиле REST были доминирующим стандартом в нашей индустрии.

Однако, у REST есть свои проблемы. Клиент может привыкнуть извлекать лишние данные, запрашивая целый ресурс в случае, когда ему нужны лишь один-два фрагмента информации. Либо клиенту могут регулярно требоваться несколько объектов одновременно, но он не может извлечь их все в одном запросе – тогда возникает так называемое «недоизвлечение» данных. Что касается поддержки, изменения в REST API могут приводить к тому, что клиенту потребуется обновить всю интеграцию, чтобы программа соответствовала новой структуре API или схемам откликов.

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

Что такое Graph API?

Упрощенное определение графового API: это API, моделирующий данные в терминах узлов и ребер (объектов и отношений) и позволяющий клиенту взаимодействовать сразу со многими узлами в рамках единственного запроса. Допустим, на сервере содержатся данные об авторах, постах в блогах и комментариях к ним. Если у нас REST API, то для получения автора и комментариев к конкретному посту с клиента, возможно, потребуется сделать три HTTP-запроса, например:

/posts/123, /authors/455, /posts/123/comments.

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

Кейс 1: Графовый API Facebook

Facebook выпустил версию 1.0 своего API в 2010 году и с тех пор проектирует новые версии, вдохновляясь примером графовых баз данных. Существуют узлы, соответствующие, например, постам и комментариям, а также ребра, соединяющие их и указывающие, что данный комментарий «относится» к этому посту. Такой подход обеспечивает всей конструкции не менее качественную обнаружимость, чем у типичного REST API, однако, все равно позволяет клиенту оптимизировать извлечение данных. Возьмем в качестве примера отдельный пост и рассмотрим, какие простые операции можно с ним проделать.

Для начала клиент при помощи запроса GET выбирает пост из корня API, исходя из ID поста.

GET /<post-id>

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

GET /<post-id>?fields=caption,created_time

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

GET /<post-id>/comments

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

 GET /<post-id>?fields=caption,created_time,comments{id,message}

Вышеприведенный запрос возвращает отклик, в котором содержится время создания поста, его заголовок и список комментариев (из каждого сообщения выбирается только id и сообщение). В REST вы бы такое сделать не смогли. Клиенту потребовалось бы сначала выбрать пост, а затем — комментарии.

А что, если клиенту потребуются более глубокие вложения?

GET /<post-id>?fields=caption,created_time,comments{id,message,from{id,name}}

В этом запросе выбираются комментарии к посту, в том числе, id и имя автора каждого комментария. Рассмотрим, как это делалось бы в REST. Клиенту потребовалось бы запросить пост, запросить комментарии, а затем в серии отдельных запросов извлечь информацию об авторе каждого комментария. Сразу набирается множество HTTP-вызовов! Однако, при проектировании в виде графа вся эта информация конденсируется в одном вызове, и в этом вызове оказывается лишь та информация, что нужна клиенту.

Наконец, последний момент, который следует отметить о графовом проектировании: любой объект, выбираемый с ребра, сам является узлом и, следовательно, его можно запросить непосредственно. Вот, например, как выбирается дополнительная информация о конкретном комментарии:

GET /<comment-id>

Обратите внимание: клиенту не нужно собирать URL вида /posts/<post-id>/comments/<comment-id>, как могло бы потребоваться при работе с REST API. Это может пригодиться в ситуациях, когда у клиента нет непосредственного доступа к id родительского объекта.

Такая же ситуация возникает при изменении данных. Например, если нам надо обновить и/или удалить объект (скажем, комментарий), применяется запрос PUT или DELETE соответственно, посылаемый непосредственно на конечную точку id. Чтобы создать объект, клиент может направить POST к соответствующему ребру узла. Так, чтобы добавить комментарий к посту, клиент делает запрос POST к ребру с комментариями от этого поста:

POST /<post-id>/comments
message=This+is+a+comment

Кейс 2: GitHub V4 GraphQL API

Другим конкурентом графового API можно считать спецификацию под названием GraphQL. Эта концепция значительно отличается от REST, здесь предоставляется всего одна конечная точка, принимающая запросы GET и POST. При всех взаимодействиях с API отправляются запросы, соответствующие синтаксису GraphQL.

В мае 2017 года GitHub выпустил 4-ю версию своего API, соответствующую этой спецификации. Чтобы попробовать, каков из себя GraphQL, давайте рассмотрим отдельные операции, которые можно проделать с репозиторием.

Чтобы выбрать репозиторий, клиент определяет запрос GraphQL:

POST /graphql

{
  "query": "repository(owner:\"zapier\", name:\"transformer\") {
    id
    description
  }"
}

В данном запросе выбирается ID и описание репозитория “transformer” с ресурса Zapier org. Здесь следует отметить несколько вещей. Во-первых, мы считываем данные с API при помощи POST, поскольку посылаем в запросе тело сообщения. Во-вторых, полезная нагрузка самого запроса записана в формате JSON, что предписано в стандарте GraphQL. В-третьих, структура запроса будет именно такой, какая указана в нашем запросе, {"data": {"repository": {"id": "MDEwOlJlcG9zaXRvcnk1MDEzODA0MQ==", "description": "..."}}} (корневой ключ data – еще один обязательный элемент, который должен присутствовать в откликах GraphQL).

Чтобы выбрать данные, относящиеся к репозиторию – например, задачи и их авторов, клиент применяет вложенный запрос:

POST /graphql

{
  "query": "repository(owner: \"zapier\", name: \"transformer\") {
    id
    description
    issues(last: 20, orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes {
        title
        body
        author {
          login
        }
      }
    }
  }"
}

Этот запрос выхватывает ID и описание репозитория, название и текст последних 20 задач, созданных в репозитории, а также логин (имя) автора каждой задачи. То есть, в каждом запросе укладывается масса информации. Вообразите, как выглядел бы REST-эквивалент такого запроса – и становится понятно, какие возможности и гибкость обеспечивает клиентам GraphQL в данном отношении.

При обновлении данных GraphQL использует концепцию под названием «мутация». В отличие от REST, где обновление выполняется путем PUT или POST измененной копии ресурса на ту же конечную точку, с которой клиент ее извлек, мутация GraphQL – это явная операция, определяемая API. Если клиенту требуется подкорректировать данные, то требуется знать, какие мутации поддерживаются на сервере. Удобно, что GraphQL позволяет обнаруживать их в рамках процесса под названием «интроспекция схемы».

Прежде, чем обсудить, что такое «интроспекция», нужно прояснить термин «схема». В GraphQL каждый API определяет набор типов, используемых при валидации запросов. До сих пор в GitHub мы работали с типами

repository, issue и author. Каждый тип описывает данные, которые в нем содержатся, а также взаимосвязи этого типа с другими. В совокупности все эти типы образуют схему API.

При наличии подробной схемы GraphQL в обязательном порядке требует, чтобы клиент имел возможность запрашивать эту схему в соответствии с синтаксисом GraphQL. Таким образом клиент может узнать возможности API путем интроспекции.

Если клиенту требуется узнать, какие мутации возможны в GitHub, можно просто запросить:

POST /graphql

{
  "query": "__type(name: \"Mutation\") {
    name
    kind
    description
    fields {
      name
      description
    }
  }"
}
 

Среди мутаций, перечисленных в отклике, находим, например, addStar, позволяющую клиенту проставить звездочку репозиторию (или любому рейтингуемому объекту). Чтобы осуществить мутацию, используется подобный запрос:

POST /graphql
{
  "query": "mutation {
    addStar(input:{starrableId:\"MDEwOlJlcG9zaXRvcnk1MDEzODA0MQ==\"}) {
      starrable {
        viewerHasStarred
      }
    }
  }"
}

В этом запросе указано, что клиент собирается применить мутацию addStar и предоставляет аргументы, необходимые для выполнения такой операции; в данном случае, это лишь ID репозитория. Обратите внимание: в данном запросе в качестве префикса запроса используется ключевое слово mutation. Так GraphQL узнает, что клиент собирается выполнить мутацию. Во всех предыдущих запросах в качестве префикса также можно было поставить ключевое слово query, но его принято использовать, если тип операции не указан. Наконец, необходимо отметить, что клиент полностью контролирует данные, содержащиеся в отклике. В данном запросе клиент требует из репозитория поле viewerHasStarred – в данном сценарии оно нас не слишком интересует, поскольку при мутации добавляется звездочка, и мы знаем, что она вернет true. Однако, если клиент совершил иную мутацию – скажем, создал задачу, то может получить в ответ сгенерированные значения, например, ID или номер задачи, а также вложенные данные, например, общее количество открытых задач в данном репозитории.

API будущего

Надеюсь, эти кейсы наглядно демонстрируют, как развивается дизайн API в SaaS-индустрии. Я не пытаюсь сказать, что за графовыми API будущее, а REST мертв. В таких архитектурах как GraphQL есть собственные проблемы. Но хорошо, что круг возможностей ширится, и в следующий раз, когда вам потребуется создать API, вы сможете взвесить все компромиссы, на которые приходится идти при том или ином варианте дизайна, и выбрать оптимальное решение.

API – графические интерфейсы программ.

API – графические интерфейсы программ.

API Direct 3D.  API OpenGL. API Microsoft DirectX.

 

API (Application Programming Interface) – графический интерфейс программ — предоставляeт разработчикам аппаратного и про­граммного обеспечения средства создания драйверов и программ, работающих быстрее на боль­шом числе платформ.

3D API позволяет программисту создавать трехмерное программное обеспечение, использующее все возможности 3D-ускорителей не прибегая к низкоуровнему программированию. 3D API делятся на стандартные (универсальные: OpenGL, Direct 3D и др.)  и собственные (специализированные: Glide, Rredline и др.). Стандартные API поддерживают широкий спектр 3D-ускорителей и освобождает программистов от низкоуровнего программирования. Собственный 3D API предназначен для одного семейства 3D-ускорителей и ограждает программистов от низкоуровнего программирования. Использование  3D API требует применения драйверов для этого 3D API. Наличие драйверов для Direct 3D и OpenGL для Win­dows является обязательным требованием ко всем 3D-ускорителям. В настоящее время существует несколько API — OpenGL (фирма SGI), Direct 3D (фирма Microsoft) и  Glide (фирма 3Dfx). Glide поддерживается только набо­ром микросхем, выпускаемым фирмой 3Dfx. Остальные API поддерживаются большинством со­временных видеоадаптеров.

API Direct 3D.  Direct 3D является частью API, называемого DirectX. Современное программ­ное обеспечение широко использует графические интерфейсы Х Win­dows и OpenGL. Этот API предназначен для облегчения программирования игровых программ. Direct 3D имеет два режима: RM (Retained mode) – абстрактный и IM (Immediale) – непосредственный. IM состоит из тонкого уровня, который взаимодействует с аппаратурой и обеспечивает самое высокое быстродействие. RM является высокоуровневым интерфейсом, обеспечивающим для программиста множество графических операций, включая инициализацию и трансформацию. Большинство 3D-игр используют режим IM. В Windows Vista реализована поддержка тех же интерфейсов Direct3D и DirectDraw, как в Windows XP, начиная с DirectX 3 (за исключением режима Retained Mode в Direct3D). Существует и еще одно ограничение для полноценных 64-битных приложений Windows XP Professional x64 Edition, поддержка функций которых под Windows Vista ограничена Direct3D9, DirectDraw7 и более новыми версиями интерфейсов.

API OpenGL. API OpenGL является открытым 3D API, который поддерживается ассоциацией крупнейших фирм таких как DEC, E&S, IBM, INTEL, INTERGRAPH, Microsoft , SGI. Этот API реализует широкий диапазон функций от вывода точки, линии, полигона до рендеринга кривых поверхностей NURBS, покрытых текстурой. OpenGL-драйвер может быть реализован в трех вариантах: ICD, MCD и мини порт. ICD (Installable Client Driver) полностью включает все стадии конвейера  OpenGL, что обеспечивает максимальное быстродействие, но разработка такого драйвера очень трудоемкий и сложный процесс. MCD (Mini Client Driver) разработан для внесения абстракции  в  конвейер  OpenGL, и поэтому написание драйвера менее трудоемко (MCD работает только в Win­dows NT). Драйвер мини-порт предназначен для одной конкретной игры, обычно для GLQuake и Quake 2. Мини-порт может работать по принципу ICD(Rage Pro), через собственый API (например, Voodoo 2) или через Direct3D (например, Intel 740). В последнем случае он называется враппером.

API Microsoft DirectX. Этот программный интерфейс был разработан еще для операционных систем Windows 95, Windows 98 и Windows NT/2000 и др. С помощью этого API увеличивается быстродействие игр, деловой графики, трехмерного звука и т. д. Несмотря на то, что DirectX был предназначен для игр, он также используется в программах NetMeeting, ActiveMovie и NetShow. Поскольку DirectX относится к уровню аппаратных абстракций (Hardware Abstraction Layer —  HAL), разработчикам программного обеспечения необходимо использовать функции DirectX, а не обращаться напрямую к видеоадаптеру, звуковой карте, джойстику и другому ап­паратному обеспечению.

DirectX также относится к уровню аппаратной эмуляции (Hardware Emulation Layer  —  HEL), что позволяет разработчику программно эмулировать те функции, ко­торые не реализованы аппаратным обеспечением. Уровень HEL «медленнее», чем HAL, но луч­ше иметь нереализованную аппаратно функцию (пусть даже медленную), чем не иметь ничего.

Отношения между аппаратным, программным обеспечением и DirectX можно продемон­стрировать следующей схемой:

  (Аппаратное обеспечение) >   (Direc+X)  >  (Програм­мное обеспечение).

                Обновление DirectX можно выполнять независимо от операционной системы. DirectX состоит из «основного» слоя, который обеспечивает доступ к звуковым устройст­вам, устройствам двухмерной и трехмерной графики, уст­ройствам ввода и процедурам установки. Программный интерфейс DirectX содержит слой Media, который состоит из API.

Слой Media DirectX пре­доставляет сервис для разработ­чиков игр, Web и интерактивных медиа-программ. Самая последняя версия DirectX доступна для бесплатной загрузки с Web-узла фирмы Mi­crosoft. Кроме того, DirectX является частью таких продуктов, как Internet Explorer, Win­dows 2000. Некоторые производители аппаратного обес­печения поставляют вместе со своими продуктами последнюю версию DirectX. Перед инсталляцией некоторые программы проверяют номер версии установленного про­граммного интерфейса. Если установленная версия устарела, то пользователю будет предло­жено установить последнюю версию. Программный интерфейс DirectX обратно совместим, т.е. последняя версия поддерживает функции всех предыдущих. Для корректной работы всех программ необходимо использовать последнюю версию программного интерфейса DirectX.

Что не является графическим api. Графические процессоры NVIDIA готовы к API Vulkan. Мы разобрались с основами Mantle. Что дальше

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

Поддержка Vulkan компанией NVIDIA непосредственно с момента его выпуска, не только на разных платформах, но и в современных играх, таких как The Talos Principle, привлекла внимание самых именитых экспертов индустрии.

“Возможность сыграть в The Talos Principle в день выпуска API – это невероятное достижение, — говорит Джон Педди (Jon Peddie), президент Jon Peddie Research. — Мультиплатформенная совместимость и полноценная поддержка драйверов для разных операционных систем, которую обеспечила NVIDIA, подтверждает ведущую роль компании в разработке API Vulkan”.

Что такое Vulkan?

Vulkan – это низкоуровневый API, который предоставляет разработчикам прямой доступ к GPU для полного контроля над его работой. Отличаясь более простыми и легкими драйверами, Vulkan демонстрирует меньшие задержки и меньшие накладные расходы при обработке графических команд (overhead) по сравнению с традиционными API OpenGL и Direct3D. Vulkan также отличается эффективной поддержкой многопоточности и позволяет многоядерным центральным процессорам более эффективно загружать графический конвейер, поднимая производительность существующего оборудования на новый уровень.

Vulkan – это первый низкоуровневый API нового поколения, который является кроссплатформенным. Разработчики могут создавать приложения для ПК, мобильных и встроенных устройств, работающих под различными операционными системами. Как и OpenGL, Vulkan – это открытый бесплатный стандарт, доступный для любой платформы. Однако NVIDIA продолжит работу над OpenGL и OpenGL ES, чтобы поддержать тех разработчиков, которые предпочитают использовать традиционные API.

Кто стоит за Vulkan?

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

Преимущества Vulkan для пользователей

Vulkan – это отличное решение для разработчиков. Новый API снижает затраты на портирование игр и открывает новые рыночные возможности для приложений на разных платформах. Важно, что драйверы NVIDIA для Windows, Linux и Android, позволяющие получить максимум возможностей от Vulkan, уже доступны. Подробнее смотрите на странице драйверов Vulkan.

Преимущества для геймеров–владельцев графических процессоров GeForce:

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

· NVIDIA предоставляет драйверы для Vulkan для всех видеокарт GeForce на базе архитектур Kepler и Maxwell, работающих под ОС Windows (Windows 7 и выше) и Linux.

· Владельцы GeForce смогут первыми сыграть в Vulkan-версию игры The Talos Principle – головоломку от Croteam, которая стала доступна вчера. «Мы и раньше успешно работали с командой NVIDIA в плане драйверной поддержки, но я был впечатлен их работой над Vulkan, — говорит старший программист Croteam Дин Секулик (Dean Sekuliuc). – NVIDIA оперативно предоставила нам новейшие бета-драйверы, чтобы мы могли быстро внедрить новый API в Serious Engine и сделать The Talos Principle одной из первых игр с поддержкой Vulkan. Отличная работа!»

Преимущества для разработчиков профессиональных приложений для Quadro:
· в наших драйверах Vulkan и OpenGL применяется бинарная архитектура, которая позволяет применять шейдеры GLSL в Vulkan. Разработчики могут или остаться на OpenGL, или перейти с OpenGL на Vulkan, чтобы воспользоваться преимуществами Vulkan. Например, благодаря многопоточной архитектуре Vulkan ядра CPU могут подготовить данные для GPU быстрее, чем раньше. Для приложений проектирования и создания цифрового контента это означает более высокую степень интерактивности при работе с большими моделями.

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

На минувшей неделе была ратифицирована финальная версия 1.0 API Vulkan. AMD и NVIDIA представили соответствующие бета-драйверы. AMD заранее выпустила бета-версию Radeon Software еще 14 февраля. NVIDIA представила драйвер GeForce 356.39, который тоже ориентирован на поддержку API Vulkan.

Подход API Vulkan очень похож на API Mantle. Суть заключается в том, чтобы разработчики получили более глубокий доступ к «железу», чтобы выжать из него максимум. Такой подход позволяет максимально избежать существующих «узких мест». С другой стороны, разработчики должны точно знать, что они делают – например, при работе с памятью. Интерфейс OpenGL не так популярен, как DirectX, но позволяет выжать больше.

Интерфейс API Vulkan в версии 1.0 поддерживается под Windows 7, Windows 8.1, Windows 10, Android и Linux. Разработчики игр пока что не объявили о поддержки в конкретных играх, но здесь стоит дождаться Games Developer Conference, которая будет проводиться с 14 по 18 марта в Сан-Франциско. Из игровых движков пока есть информация о Source 2, который уже поддерживает API Vulkan. Процесс отладки облегчается поддержкой Valve, LunarG и Codeplay.

The Talos Principle

Хорошо, но какая игра или движок поддерживают API Vulkan? Игра The Talos Principle разрабатывалась компанией Croteam, которая и в прошлом была известна поддержкой многих графических API. И в последней итерации игра The Talos Principle не стала исключением – она поддерживает DirectX 9, DirectX 11, OpenGL и теперь Vulkan. Для студии разработчиков Vulkan является пробным шаром, хотя API Vulkan доступен в версии 1.0, поддержка пока находится в бета-стадии. На добавление поддержки разработчики Croteam затратили порядка трех месяцев. Но универсальный характер API позволяет вскоре представить вариант Linux.

API Vulkan теоретически совместим с несколькими платформами – но пока что тесты и сравнения можно провести только под Windows, причем здесь имеются свои ограничения. Реализация пока остается на очень раннем этапе. Путь рендеринга DirectX 11 совершенствовался многие годы, поэтому потенциала для оптимизации здесь уже нет. Здесь ситуация больше зависит от разработчиков драйверов, а именно AMD и NVIDIA. Игра The Talos Principle стала первой с поддержкой Vulkan. Поэтому пока нет возможности сделать сравнительный тест для оценки хорошей или плохой реализации поддержки.

Новые технологии первое время реализуются в примерах, подготовленных производителями. В случае DirectX 12 акцент был выставлен на Draw Calls, тот же тест 3DMark DirectX 12 опирается только на измерение производительности Draw Calls, игры DirectX 12, подобные Star Wars, тоже пытаются задействовать подобную нагрузку. Но The Talos Principle не так сильно зависит от высокой скорости Draw Call, чтобы низкоуровневый API дал большую разницу.

Поддержка API Vulkan версии 1.0 находится на ранней стадии, то же самое касается драйверов AMD и NVIDIA. Оба драйвера, по сути, относятся к бета-версиям, именно так их рассматривают производители GPU. Здесь обычно нет новых улучшений производительности или поддержки новых технологий,

Что такое API / Хабр

Содержание

Слово «API» мелькает в вакансиях даже для начинающих тестировщиков. То REST API, то SOAP API, то просто API. Что же это за зверь такой? Давайте разбираться!

— А зачем это мне? Я вообще-то web тестирую! Вот если пойду в автоматизацию, тогда да… Ну, еще это в enterprise тестируют, я слышал…

А вот и нет! Про API полезно знать любому тестировщику. Потому что по нему системы взаимодействуют между собой. И это взаимодействие вы видите каждый день даже на самых простых и захудалых сайтах.

Любая оплата идет через API платежной системы. Купил билет в кино? Маечку в онлайн-магазине? Книжку? Как только жмешь «оплатить», сайт соединяет тебя с платежной системой.

Но даже если у вас нет интеграции с другими системами, у вас всё равно есть API! Потому что система внутри себя тоже общается по api. И пока фронт-разработчик усиленно пилит GUI (графический интерфейс), вы можете:

• скучать в ожидании;
• проверять логику работы по API

Конечно, я за второй вариант! Так что давайте разбираться, что же такое API. Можно посмотреть видео на youtube, или прочитать дальше в виде статьи.

Что такое API

API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».

Если переводить на русский, это было бы слово «договор». Договор между двумя сторонами, как договор на покупку машины:

• мои обязанности — внести такую то сумму,
• обязанность продавца — дать машину.

Перевести можно, да. Но никто так не делает ¯\_(ツ)_/¯

Все используют слово «контракт». Так принято. К тому же это слово входит в название стиля разработки:

• Code first — сначала пишем код, потом по нему генерируем контракт
• Contract first — сначала создаем контракт, потом по нему пишем или генерируем код (в этой статье я буду говорить именно об этом стиле)

Мы же не говорим «контракт на продажу машины»? Вот и разработчики не говорят «договор». Негласное соглашение.

API — набор функций

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

Соответственно, API отвечает на вопрос “Как ко мне, к моей системе можно обратиться?”, и включает в себя:

• саму операцию, которую мы можем выполнить,
• данные, которые поступают на вход,
• данные, которые оказываются на выходе (контент данных или сообщение об ошибке).

Тут вы можете мне сказать:

— Хмм, погоди. Операция, данные на входе, данные на выходе — как-то всё это очень сильно похоже на описание функции!

Если вы когда-то сталкивались с разработкой или просто изучали язык программирования, вы наверняка знаете, что такое функция. Фактически у нас есть данные на входе, есть данные на выходе, и некая магия, которая преобразует одно в другое.

И да! Вы будете правы в том, что определения похожи. Почему? Да потому что API — это набор функций. Это может быть одна функция, а может быть много.

Как составляется набор функций

Да без разницы как. Как разработчик захочет, так и сгруппирует. Например, можно группировать API по функционалу. То есть:

• отдельно API для входа в систему, где будет регистрация и авторизация;
• отдельно API для отчетности — отчет 1, отчет 2, отчет 3… отчет N. Для разных отчетов у нас разные формулы = разные функции. И все мы их собираем в один набор, api для отчетности.
• отдельно API платежек — для работы с каждым банком своя функция.
• …

Можно не группировать вообще, а делать одно общее API.

Можно сделать одно общее API, а остальные «под заказ». Если у вас коробочный продукт, то в него обычно входит набор стандартных функций. А любые хотелки заказчиков выносятся отдельно.

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

И конечно, функции можно переиспользовать. То есть одну и ту же функцию можно включать в разные наборы, в разные апи. Никто этого не запрещает.

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

При чем тут слово «интерфейс»

— Минуточку, Оля! Ты же сама выше писала, что API — это Application programming interface. Почему ты тогда говоришь о контракте, хотя там слово интерфейс?

Да потому, что в программировании контракт — это и есть интерфейс. В классическом описании ООП (объектно-ориентированного программирования) есть 3 кита:

1. Инкапсуляция
2. Наследование
3. Полиморфизм

Инкапсуляция — это когда мы скрываем реализацию. Для пользователя все легко и понятно. Нажал на кнопочку — получил отчет. А как это работает изнутри — ему все равно. Какая база данных скрыта под капотом? Oracle? MySQL? На каком языке программирования написана программа? Как именно организован код? Не суть. Программа предоставляет интерфейс, им он и пользуется.

Не всегда программа предоставляет именно графический интерфейс. Это может быть SOAP, REST интерфейс, или другое API. Чтобы использовать этот интерфейс, вы должны понимать:

• что подать на вход;
• что получается на выходе;
• какие исключения нужно обработать.

Пользователи работают с GUI — graphical user interface. Программы работают с API — Application programming interface. Им не нужна графика, только контракт.
Вызвать апи можно как напрямую, так и косвенно.

Напрямую:

1. Система вызывает функции внутри себя
2. Система вызывает метод другой системы
3. Человек вызывает метод
4. Автотесты дергают методы

Косвенно:

1. Пользователь работает с GUI

Вызов API напрямую

1. Система вызывает функции внутри себя

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

Это самый «простой» в использовании способ, потому что автор API, которое вызывается — разработчик. И он же его потребитель! А значит, проблемы с неактуальной документацией нет =)

Шучу, проблемы с документацией есть всегда. Просто в этом случае в качестве документации будут комментарии в коде. А они, увы, тоже бывают неактуальны. Или разработчики разные, или один, но уже забыл, как делал исходное api и как оно должно работать…

2. Система вызывает метод другой системы

А вот это типичный кейс, которые тестируют тестировщики в интеграторах. Или тестировщики, которые проверяют интеграцию своей системы с чужой.

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

Допустим, я решила подключить подсказки из Дадаты к своему интернет-магазинчику, чтобы пользователь легко ввел адрес доставки.

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

• Он вводит букву на моем сайте
• Мой сайт отправляет запрос в подсказки Дадаты по API
• Дадата возвращает ответ
• Мой сайт его обрабатывает и отображает результат пользователю

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

И, конечно, не забываем про кейс, когда мы разрабатываем именно API-метод. Который только через SOAP и можно вызвать, в интерфейсе его нигде нет. Что Заказчик заказал, то мы и сделали ¯\_(ツ)_/¯

Пример можно посмотреть в Users. Метод MagicSearch создан на основе реальных событий. Хотя надо признать, в оригинале логика еще замудренее была, я то под свой сайт подстраивала.

Но тут фишка в том, что в самой системе в пользовательском интерфейсе есть только обычный поиск, просто строка ввода. Ну, может, парочка фильтров. А вот для интеграции нужна была целая куча доп возможностей, что и было сделано через SOAP-метод.

Функционал супер-поиска доступен только по API, пользователь в интерфейсе его никак не пощупает.

В этом случае у вас обычно есть ТЗ, согласно которому работает API-метод. Ваша задача — проверить его. Типичная задача тестировщика, просто добавьте к стандартным тестам на тест-дизайн особенности тестирования API, и дело в шляпе!

(что именно надо тестировать в API — я расскажу отдельной статьей чуть позднее)

3. Человек вызывает метод

Причины разные:

1. Для ускорения работы
2. Для локализации бага (проблема где? На сервере или клиенте?)
3. Для проверки логики без докруток фронта

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

Для примера снова идем в Users. Если мы хотим создать пользователя, надо заполнить уйму полей!

Конечно, это можно сделать в помощью специальных плагинов типа Form Filler. Но что, если вам нужны адекватные тестовые данные под вашу систему? И на русском языке?

Заполнение полей вручную — грустно и уныло! А уж если это надо повторять каждую неделю или день на чистой тестовой базе — вообще кошмар. Это сразу первый приоритет на автоматизацию рутинных действий.

И в данном случае роль автоматизатора выполняет… Postman. Пользователя можно создать через REST-запрос CreateUser. Один раз прописали нормальные “как настоящие” данные, каждый раз пользуемся. Профит!

Вместо ручного заполнения формы (1 минута бездумного заполнения полей значениями «лпрулпк») получаем 1 секунду нажатия на кнопку «Send». При этом значения будут намного адекватнее.

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

Если вы нашли баг и не понимаете, на кого его вешать — разработчика front-end или back-end, уберите все лишнее. Вызовите метод без графического интерфейса. А еще вы можете тестировать логику программы, пока интерфейс не готов или сломан.

4. Автотесты дергают методы

Есть типичная пирамида автоматизации:

• GUI-тесты — честный тест, «как это делал бы пользователь».
• API-тесты — опускаемся на уровень ниже, выкидывая лишнее.
• Unit-тесты — тесты на отдельную функцию

Слово API как бы намекает на то, что будет использовано в тестах ツ

Допустим, у нас есть:

• операция: загрузка отчета;
• на входе: данные из ручных или автоматических корректировок или из каких-то других мест;
• на выходе: отчет, построенный по неким правилам

Правила построения отчета:

• Ячейка 1: Х — Y
• Ячейка 2: Z * 6
• …

GUI-тесты — честный тест, робот делает все, что делал бы пользователь. Открывает браузер, тыкает на кнопочки… Но если что-то упадет, будете долго разбираться, где именно.

API-тесты — все то же самое, только без браузера. Мы просто подаем данные на вход и проверяем данные на выходе. Например, можно внести итоговый ответ в эксельку, и пусть робот выверяет ее, правильно ли заполняются данные? Локализовать проблему становится проще.

Unit-тесты — это когда мы проверяем каждую функцию отдельно. Отдельно смотрим расчет для ячейки 1, отдельно — для ячейки 2, и так далее. Такие тесты шустрее всего гоняются и баги по ним легко локализовать.

Косвенный вызов API

Когда пользователь работает с GUI, на самом деле он тоже работает с API. Просто не знает об этом, ему это просто не нужно.

То есть когда пользователь открывает систему и пытается загрузить отчет, ему не важно, как работает система, какой там magic внутри. У него есть кнопочка «загрузить отчет», на которую он и нажимает. Пользователь работает через GUI (графический пользовательский интерфейс).

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

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

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

В первую очередь, мы подразумеваем тестирование ЧЕРЕЗ API. «Тестирование API» — общеупотребимый термин, так действительно говорят, но технически термин некорректен. Мы не тестируем API, мы не тестируем GUI (графический интерфейс). Мы тестируем какую-то функциональность через графический или программный интерфейс.

Но это устоявшееся выражение. Можно использовать его и говорить “тестирование API”. И когда мы про это говорим, мы имеем в виду:

• автотесты на уровне API
• или интеграцию между двумя разными системами.

Интеграция — когда одна система общается с другой по какому-то протоколу передачи данных. Это называется Remote API, то есть общение по сети, по некоему протоколу (HTTP, JMS и т.д.). В противовес ему есть еще Local API (он же «Shared memory API») — это то API, по которому программа общается сама с собой или общается с другой программой внутри одной виртуальной памяти.

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

И если вы видите в вакансии «тестирование API», скорее всего это подразумевает умение вызвать SOAP или REST сервис и протестировать его. Хотя всегда стоит уточнить!

API (Application programming interface) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».

Контракт включает в себя:

• саму операцию, которую мы можем выполнить,
• данные, которые поступают на вход,
• данные, которые оказываются на выходе (контент данных или сообщение об ошибке).
».

в чем же фишка? / Хабр

На WWDC 2014 всех нас ждал сюрприз: анонс нового графического 3D API под названием Metal. Но на этот раз мы имеем дело не с новым высокоуровневым API поверх OpenGL ES (как было в случае с Scene Kit), а с новым низкоуровневым API для рендеринга и вычислений, которое может служить заменой OpenGL в играх. По словам Apple, Metal может быть до 10 раз быстрее, чем OpenGL ES (точнее говоря — может генерировать вызовы отрисовки [draw calls; передача данных на GPU] в 10 раз быстрее) и доступен только на устройствах с iOS и процессором последнего поколения A7.

Этот анонс спровоцировал новую волну обсуждения и споров насчет необходимости появления новых графических API, которые должны (или не должны — кто знает) заменить OpenGL. Предлагаемый вашему вниманию пост не намерен участвовать в этой дискуссии – его целью является разъяснение того, чем все-таки Metal отличается от OpenGL ES, чьей заменой он является. Чтобы понять, что такого особенного (или же наоборот, ничего особенного) есть в Metal API, нам придется немного заглянуть под «капот» графических API и GPU.

Как работают GPU и графические API

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

Для простого улучшения в работе GPU этот процесс стоит запустить асинхронно; тогда GPU не будет блокировать CPU и вызовы API будут возвращать результат почти мгновенно. В этом случае GPU возможно не будет использоваться на все 100%, поскольку ему возможно придется ждать от CPU новых вызовов рендеринга (= начала кадра), в то время как вызовы остальных команд будут ждать завершения предыдущих. Это становится причиной того, почему большинство графических драйверов собирают все вызовы отрисовки (и другие задачи, которые нужно будет выполнить на GPU — например, изменение состояний) для отрисовки всего кадра перед отправкой его на GPU. Эти буферизованные команды будут затем отосланы обратно после того, как будет получена команда для отрисовки следующего кадра, благодаря чему GPU будет использоваться настолько эффективно, насколько это возможно. Конечно, это добавит один кадр задержки: пока CPU будет создавать задание для текущего фрейма, прошлый фрейм будет рендериться на GPU. На самом деле, можно буферизовать больше одного кадра и таким образом добиваться большей частоты смены кадров — за счет еще большей задержки.

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

Итак, мы узнали как минимум две важные вещи о том, что происходит за сценой совместной работы OpenGL с современными GPU: изменение состояний может быть сложным, если требуется новая комбинация состояний и все операции на GPU будут задержаны на некоторое количество времени.

В приложении, один поток актуальных команд для одного кадра, которые надо выполнить на GPU, формируется и отправляется на GPU сразу весь за один раз (на самом деле все немного сложнее, но давайте не будет пока углубляться).

Подробнее прочитать о том, как работает современный пайплайн компьютерной графики вы можете в серии статей Fabian Giesens — “A trip down the Graphics Pipeline“.

Почему у другой программной модели могут быть преимущества

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

Некоторые графические API сегодня пытаются убрать большую часть этих трюков, раскрывая скрываемую ими «запутанность» – и в некоторых случаях оставляя на волю программы решение всех связанных проблем. В этом направлении шли графические API PS3, в нем же идет AMD со своим Mantle, туда же собираются грядущие DirectX 12 и Apple Metal.

Что же изменилось?

Буферы команд теперь открыты и приложение должно заполнять эти буферы и отправлять их в очередь команд, которая будет выполнять эти буферы в заданном порядке на GPI — таким образом приложение будет иметь полный контроль над заданием, отправляемым на GPU, и определять, сколько кадров задержки необходимо добавить (добавляя задержку, но при этом увеличивая степень используемости GPU). Буферизация команд на GPU и отправка их асинхронно в следующий фрейм должна быть реализована самим приложением.

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

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

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

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

И как это в 10 раз быстрее?

Каждый вызов отрисовки стоит сколько-то времени на CPU и сколько-то времени на GPU. Metal API уменьшает время, затрачиваемое CPU, благодаря упрощению контроля за состояниями и благодаря этому уменьшению числу проверок на ошибки от драйвера на правильность комбинаций состояний. Еще помогает предварительное вычисление состояний: можно не просто выполнять проверку на ошибки во время билда, но и само изменения состояния потребует меньшее количество вызовов API. Возможность параллельного построения буферов команд еще больше увеличивает число вызовов отрисовки в том случае, если приложение привязано к CPU.

А вот рендеринг на GPU с другой стороны быстрее не становится, приложение которое делает совсем немного вызовов отрисовки для больших мешей (меш — часть модели, состоящая из вершин объекта] не получит никакого преимущества от перехода на Metal.

Может ли то же самое быть сделано на OpenGL?

На GDC 14 была отличная презентация “Approaching Zero Driver Overhead” за авторством Cass Everitt, John McDonald, Graham Sellers и Tim Foley. Основной ее идеей было уменьшение работы драйвера в OpenGL при помощи увеличения количества работы, производимым вызовов отрисовки, и использованием новых объектов GL и меньшего количества числа вызовов GL для повышения эффективности.

Эта и другие идеи потребуют дальнейшего расширения OpenGL и появления новых версий этого API, но многое из этого можно будет перенести в OpenGL ES. Что мы потеряем — так это возможность прямого управления командными буферами, со всеми своими «за» и «против».

Какова вероятность увидеть это в будущем? Из-за поддержки обратной совместимости, остается надеяться только на появление некоего набора функций, который можно будет назвать «современное ядро», но и его скорее всего придется сделать совместимым со всем вплоть до оригинальной функции glBegin(). Это ограничение будет действовать на протяжении всего потенциального будущего OpenGL и станет пределом его эволюции, делая альтернативы вроде Metal API все более предпочитаемыми…

Оригинал статьи:
http://renderingpipeline.com/2014/06/whats-the-big-deal-with-apples-metal-api/

Что такое API? API – простым языком

API (application programming interface) – интерфейс прикладного программирования, или программный интерфейс приложений, или программный интерфейс для приложений. Так переводится с английского аббревиатура API . Если вы не программист, то звучит грозно, не правда ли?

Теперь давайте проверим ваш IQ. Первое объяснение для людей с коэффициентом от 100 и выше. Второе, для всех остальных людей.

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

Итак, что же такое интерфейс прикладного программирования или API?

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

Для тех, кто не привык к техническим терминам, есть более простые объяснения, основанные на ассоциациях.

Например: можно представить API в виде розетки, соединяющей источник электроэнергии с одной стороны и пользователей этой энергии, с другой. Источник энергии предоставляет пользователям специальный вход, розетку (API), пользователи, имея специальное устройство определенной конфигурации – вилку, получают возможность подключение.

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

По сути, если бы не было API, не было бы Windows, поскольку всё это множество программ взаимодействует между собой, использует ресурсы операционной системы и «железа», именно с помощью API.

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

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

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

Крупные издания, к примеру, The New York Times, именно с помощью API предоставляют доступ  к своей базе данных, в которой хранится не одна тысяча статей.

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

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

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

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

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

Какое практическое применение API может быть? Есть применение, если вы, программист.

Большинство крупных приложений открывают свои API и предоставляют возможность пользоваться ими.

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

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

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

Урок 7. Как получать данные через API

В этом уроке вы узнаете:

1. Как получать объекты
2. Тренировка в Песочнице
3. Задание
4. Что дальше
5. Полезные ссылки
6. Вопросы

В этом уроке мы расскажем о структуре API и рассмотрим несколько примеров получения данных.

Напомним схему взаимосвязи объектов в API Директа, которую мы показывали в первом уроке:

Для каждого класса объектов в API предусмотрен соответствующий сервис: Campaigns — для управления кампаниями, AdGroups — для управления группами объявлений, Ads — для управления объявлениями и т. д. Полный список сервисов приведен в документации.

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

• add — добавление объектов;

• update — изменение параметров объектов;

• delete — удаление объектов;

• get — получение объектов.

В сервисе могут быть и другие методы. Например, в сервисе Campaigns доступны следующие методы:

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

Метод get разработан так, чтобы можно было запрашивать только нужные данные. Например, можно получить только идентификаторы и названия кампаний, а не все их параметры. Имена нужных вам параметров необходимо перечислить во входном параметре FieldNames.

Критерии отбора объектов нужно указать во входной структуре SelectionCriteria. Если критериев отбора несколько, то сервер будет искать объекты, подходящие сразу под все критерии. Некоторые сервисы позволяют указывать пустую структуру SelectionCriteria — в этом случае возвращаются все объекты.

Напомним пример запроса из предыдущего урока. В этом примере мы получили весь список кампаний, указав пустую структуру SelectionCriteria, и для каждой кампании получили только идентификатор и название, указав соответствующие параметры в FieldNames.

Внимание. Не забудьте изменить токен и идентификаторы в примерах на ваши данные.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{},\"FieldNames\":[\"Id\",\"Name\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {},
    "FieldNames": ["Id", "Name"]
  }
}

Ответ

{
  "result": {
    "Campaigns": [{
      "Name": "Test API Sandbox campaign 1",
      "Id": 1234567
    }, {
      "Name": "Test API Sandbox campaign 2",
      "Id": 1234578
    }, {
      "Name": "Test API Sandbox campaign 3",
      "Id": 1234589
    }]
  }
}

Некоторые параметры кампании (такие как название и идентификатор) являются общими для всех типов кампаний, а некоторые (например, стратегии показа) зависят от типа кампании. В следующем примере мы получим только кампании с типом «Текстово-графические объявления». Чтобы получить для таких кампаний стратегии показа, укажем имя соответствующего параметра во входном параметре TextCampaignFieldNames.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{ "Types": ["TEXT_CAMPAIGN"]},"FieldNames":["Id","Name"],"TextCampaignFieldNames":["BiddingStrategy"]}}' https://api-sandbox.direct.yandex.com/json/v5/campaigns

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{ \"Types\": [\"TEXT_CAMPAIGN\"]},\"FieldNames\":[\"Id\",\"Name\"],\"TextCampaignFieldNames\":[\"BiddingStrategy\"]}}" https://api-sandbox.direct.yandex.com/json/v5/campaigns

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "Types": ["TEXT_CAMPAIGN"]
    },
    "FieldNames": ["Id", "Name"],
    "TextCampaignFieldNames": ["BiddingStrategy"]
  }
}

Ответ

{
  "result": {
    "Campaigns": [{
      "Id": 1234567,
      "Name": "Test API Sandbox campaign 1",
      "TextCampaign": {
        "BiddingStrategy": {
          "Search": {
            "BiddingStrategyType": "HIGHEST_POSITION"
          }, 
          "Network": {
            "BiddingStrategyType":"NETWORK_DEFAULT",
            "NetworkDefault": {
              "LimitPercent": 100
            }
          } 
        }
      }
    }]
  }
}

Постраничная выборка

Если вы работаете с большими массивами данных, все объекты могут не уместиться в ответе на один запрос, так как метод get возвращает не более 10 000 объектов. В этом случае метод get возвращает параметр LimitedBy — порядковый номер последнего возвращенного объекта. Наличие этого параметра указывает, что не все объекты получены.

Настроить параметры постраничной выборки можно с помощью входной структуры Page. Укажите количество нужных объектов — например, 10 — и количество объектов, которое должно быть пропущено при выборке, — например, 20, — и вы получите порцию данных: 10 объектов с 21-го по 30-й.

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

Сервис AdGroups

Получение списка групп объявлений кампании.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"CampaignIds":[ИДЕНТИФИКАТОР_КАМПАНИИ]},"FieldNames":["Id","Name","Status","Type"]}}' https://api-sandbox.direct.yandex.com/json/v5/adgroups

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"CampaignIds\":[ИДЕНТИФИКАТОР_КАМПАНИИ]},\"FieldNames\":[\"Id\",\"Name\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/adgroups

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "CampaignIds": [ИДЕНТИФИКАТОР_КАМПАНИИ]
    },
    "FieldNames": ["Id", "Name", "Status", "Type"]
  }
}

Ответ

{
  "result": {
    "AdGroups": [{
      "Status": "ACCEPTED",
      "Name": "Группа №1296502",
      "Id": 1296502,
      "Type": "TEXT_AD_GROUP"
    }, {
      "Name": "Группа №1296517",
      "Status": "DRAFT",
      "Id": 1296517,
      "Type": "TEXT_AD_GROUP"
    }]
  }
}

Сервис Ads

Получение списка объявлений группы.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","State","Status","Type"]}}'  https://api-sandbox.direct.yandex.com/json/v5/ads

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"State\",\"Status\",\"Type\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [ИДЕНТИФИКАТОР_ГРУППЫ]
    },
    "FieldNames": ["Id", "State", "Status", "Type"]
  }
}

Ответ

{
  "result": {
    "Ads": [{
      "State": "ON",
      "Id": 1381459,
      "Status": "ACCEPTED",
      "Type": "TEXT_AD"
    }, {
      "Type": "TEXT_AD",
      "Status": "DRAFT",
      "Id": 1381470,
      "State": "OFF"
    }]
  }
}

Получение параметров одного объявления.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"Ids":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},"FieldNames":["Id"],"TextAdFieldNames":["Text","Title","Href","VCardId"]}}' https://api-sandbox.direct.yandex.com/json/v5/ads

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"Ids\":[ИДЕНТИФИКАТОР_ОБЪЯВЛЕНИЯ]},\"FieldNames\":[\"Id\"],\"TextAdFieldNames\":[\"Text\",\"Title\",\"Href\",\"VCardId\"]}}" https://api-sandbox.direct.yandex.com/json/v5/ads

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "Ids": [1381459]
    },
    "FieldNames": ["Id"],
    "TextAdFieldNames": ["Text", "Title", "Href", "VCardId"]
  }
}

Ответ

{
  "result": {
    "Ads": [{
      "Id": 1381459,
      "TextAd": {
        "Title": "Test sandbox banner 5",
        "Href": "http://www.yandex.ru",
        "VCardId": 171518,
        "Text": "Test sandbox banner 5 text"
      }
    }]
  }
}

Сервис Keywords

Получение ключевых фраз группы объявлений.

cURL

curl -k -H "Authorization: Bearer ТОКЕН" -d '{"method":"get","params":{"SelectionCriteria":{"AdGroupIds":[ИДЕНТИФИКАТОР_ГРУППЫ]},"FieldNames":["Id","Keyword","Bid","State","Status"]}}' https://api-sandbox.direct.yandex.com/json/v5/keywords

cURL для Windows

curl -k -H "Authorization: Bearer ТОКЕН" -d "{\"method\":\"get\",\"params\":{\"SelectionCriteria\":{\"AdGroupIds\":[ИДЕНТИФИКАТОР_ГРУППЫ]},\"FieldNames\":[\"Id\",\"Keyword\",\"Bid\",\"State\",\"Status\"]}}" https://api-sandbox.direct.yandex.com/json/v5/keywords

Запрос

{
  "method": "get",
  "params": {
    "SelectionCriteria": {
      "AdGroupIds": [1296506]
    },
    "FieldNames": ["Id", "Keyword", "Bid", "State", "Status"]
  }
}

Ответ

{
  "result": {
    "Keywords": [{
      "State": "ON",
      "Keyword": "test keyword 5.1",
      "Status": "ACCEPTED",
      "Bid": 7700000,
      "Id": 3458327
    }, {
      "Keyword": "Новая фраза",
      "Id": 3458351,
      "Bid": 400000,
      "Status": "ACCEPTED",
      "State": "ON"
    }]
  }
}

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

Документация: Как работает метод get

1. Для чего предназначен сервис Campaigns API Директа?

График

— предупреждающие сообщения на графике рассеяния R «не является графическим параметром»

Переполнение стека

1. Около
2. Товары
3. Для команд

1. Переполнение стека Общественные вопросы и ответы
2. Переполнение стека для команд Где разработчики и технологи делятся частными знаниями с коллегами
3. работы Программирование и связанные с ним технические возможности карьерного роста
4. Талант Нанимайте технических специалистов и создавайте свой бренд работодателя
5. реклама Обратитесь к разработчикам и технологам со всего мира
6. О компании

,Моделирование

— что это за графическое обозначение?

Переполнение стека

1. Около
2. Товары
3. Для команд

1. Переполнение стека Общественные вопросы и ответы
2. Переполнение стека для команд Где разработчики и технологи делятся частными знаниями с коллегами
3. работы Программирование и связанные с ним технические возможности карьерного роста
4. Талант Нанимайте технических специалистов и создавайте свой бренд работодателя
5. реклама Обратитесь к разработчикам и технологам со всего мира
6. О компании

,

plot — R: построение функции, а не графического параметра

Переполнение стека

1. Около
2. Товары
3. Для команд

1. Переполнение стека Общественные вопросы и ответы
2. Переполнение стека для команд Где разработчики и технологи делятся частными знаниями с коллегами
3. работы Программирование и связанные с ним технические возможности карьерного роста
4. Талант Нанимайте технических специалистов и создавайте свой бренд работодателя
5. реклама Обратитесь к разработчикам и технологам со всего мира
6. О компании

,

c ++ — Портативное окно рендерера в реальном времени без графического API

Переполнение стека

1. Около
2. Товары
3. Для команд

1. Переполнение стека Общественные вопросы и ответы
2. Переполнение стека для команд Где разработчики и технологи делятся частными знаниями с коллегами
3. работы Программирование и связанные с ним технические возможности карьерного роста
4. Талант Нанимайте технических специалистов и создавайте свой бренд работодателя
5. реклама Обратитесь к разработчикам и технологам со всего мира
6. О компании

,