Разное

Api данные: Что такое API / Хабр

Содержание

Что такое 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) — это контракт, который предоставляет программа. «Ко мне можно обращаться так и так, я обязуюсь делать то и это».

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

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

  • ».

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

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

Читать далее

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Регистрируйтесь и учитесь на Coursera: сертификаты в резюме и дипломные программы от лучших университетов и компаний мира.

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

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

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

В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой,  могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную, внутреннюю логику, которая скрыта от окружения и не является 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 просто существует. Ну, а если вы действительно интересуетесь программированием,  обязательно присмотритесь к этому направлению организации взаимодействия различных приложений. Очень часто, это сильно упрощает жизнь.

телеграм канал. Подпишись, будет полезно!

Что такое API и как этим пользоваться?

Готовы узнать все об API? Что такое аффилированный API, и как вы можете этим пользоваться?

Тогда поехали!

Введение

Вы наверное безумец, если не согласны со следующим утверждением:

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

Однако, вам кажется, что вы не совсем понимаете что это такое.

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

Не беспокойтесь! Эта статья – то, чего вы так долго ждали!

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

К концу прочтения статьи вы будете знатоком этой темы!

Хватит вступлений. Начнем, пожалуй!

Что такое API?

Сейчас, скорее всего, вы задаетесь вопросом: “как расшифровывается API?”

API это Application Program Interface или программный интерфейс приложения.

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

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

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

API: прагматическое использование

API изначально использовался в качестве метода отправки команд и информации определенного формата с одних программ на другие.

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

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

Представьте, что вы хотите разработать программу.

Вы пишете код и программируете как профессионал.

Advertisement

И что теперь?

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

Но как?

Просто!

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

Что было до API?

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

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

В чем была проблема?

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

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

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

Как API используются в контексте всемирной паутины?

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

Пример того, как используется API:

Знаете, почему вы можете быстро зарегистрироваться в разных приложениях, используя только аккаунт Facebook?

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

Что будет, если не использовать API?

Если вы решите не использовать API, приложение может, например, узнать о новой статье Академии Mobidea открыв www.academy.mobidea.com

Затем приложение прочтет веб страницу, как если бы оно было человеком, и интерпретирует контент страницы, в данном случае – Академии.

Та же ситуация с использованием API: приложение находит информацию о веб странице www.academy.mobidea.com , отправив сообщение на API Академии Mobidea.

Сообщение отправляется в формате JSON.

Что такое формат JSON?

Формат JSON (JavaScript Object Notation) это файл открытого стандарта, содержащий объекты данных и соответствующие атрибуты. 

Например, когда мы проверяем новые статьи в Академии Mobidea, передаваемый JSON файл выглядел бы так:

article {

title: “Новая статья”,

date: 01/01/2017,

content: “Много текста.”,

author: “Джон Уайт”

}

Далее, после отправки сообщения в формате JSON, API страницы www.academy.mobidea.com реагирует структурированным ответом, похожим на пример выше.

Почему метод передачи информации так важен?

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

Это значит, что информация остается неизменной, вне зависимости от того, меняет ли веб страница свой внешний вид и дизайн или нет.

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

Что случится, если сайт поменяется, и при этом API не был использован?

Скорее всего приложение перестанет работать!

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

Оно просто не сможет понять данные, передаваемые с данного вебсайта.

В итоге, API это более безопасный и надежный вариант.

С ним вы можете быть уверены в том, что приложение продолжит работать с сайтом.

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

Типы API

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

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

Также есть и Web API.

Самые известные типы API:

  • Удаленный вызов процедур (Remote Procedure Call – RPC)
  • Простой протокол доступа к объектам (Simple Object Access Protocol – SOAP)
  • Передача состояния представления (Representational State Transfer – REST)

Все еще недостаточно?

Больше примеров?

Подумайте о Windows, компьютерной операционной системе, разработанной Microsoft для работы с ПК (персональными компьютерами).

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

Более того, Windows – не единственная операционка, которая предоставляет API. Большинство ОС это делают.

Какая цель?

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

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

Примеры API

Не так сложно найти примеры API.

Почему?

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

Гиганты технологий, такие как Twitter, YouTube и Facebook, например, все работают с API.

Twitter использует REST API, которые дают программный доступ для чтения и написания данных Twitter.

У разработчиков есть доступ к ключевым данным Twitter.

К тому же  поисковые API дают разработчикам методы для взаимодействия с данными трендов и поиском Twitter.

YouTube также использует API.

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

Вот некоторые из API YouTube:

YouTube Player API, YouTube Data API, YouTube Live Streaming API, YouTube Analytics API.

Как насчет Facebook? Как используется API в этом случае?

Заметьте, что вы можете оставлять Facebook комментарии на любом сайте и синхронизировать эти комментарии со страницей на Facebook.

API!

Это отличный пример того, как можно использовать API по-максимуму и, к примеру,  упростить работу блоггеров.

API позволяет пользователям оставлять комментарии в блоге.

Этот комментарий также появляется на Facebook странице, связанной с этим блогом. И это удобно всем!

Преимущество API

Использование API имеет ряд преимуществ.

Мы не нашли весь их список в алфавитном порядке и поэтому выделили несколько самых важных:

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

Как использовать API в партнерском маркетинге?

В партнерском маркетинге API также играет важную роль.

В прошлом программистам приходилось работать с интеграцией SaaS, где большая часть работы выполняется вручную.

Этот процесс был хаотичным и отнимал много времени, останавливая развитие партнерских программ. IT отделы тратили время на рутинные процессы.

API интеграция определенно помогает в работе всем программистам, которые работают в партнерках.

Какие типы аффилированных API используются в Mobidea?

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

На данный момент у нас есть Statistics API, через который пользователи могут проверить статистику, и Offers API, в котором пользователи могут увидеть оферы.

Рассмотрим функциональность этих двух API более подробно!

Mobidea’s Statistics API

API статистики позволяет аффилиатам получать список со статистикой в выбранном формате (XML, JSON) для заданного дня (устанавливается в параметре &date) и доходом, показанным в выбранной валюте.

Список может быть настроен так, чтобы передавать только выбранные поля (дата, время, оператор, код страны, track1..track5, доход).

API оферов Mobidea

API оферов дает пользователям возможность получить список своих оферов в выбранном формате (XML, JSON) с отображаемой выплатой, показанной в выбранной валюте.

Данные в списке можно сортировать по статусу (в ажидании, одобрено или отклонено), категориям оферов и ограничениям.

Более того, пользователь может настроить данные так, чтобы передавать только выбранные поля (имя, описание, статус, категория, выплата, ограничения, иконка, баннеры, URL).

Аффилиаты могут использовать эти ссылки API для импорта данных на разные платформы и просмотра статистики продаж.

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

Интегрируя API, предоставленные Mobidea, вы сможете просматривать как оферы, так и статистику, доступные в вашей любимой партнерской программе!

Заключение

Теперь, когда вы знаете, что такое API и как его использовать, важно использовать весь потенциал API.

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

Что теперь?

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

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

Пока!

Advertisement

5489

Метки:
НачалоПартнерский МаркетингПодсказки

Что еще почитать

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

Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. DEV.BY опубликовал пояснение разработчика Петра Газарова (он рассказал об 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.

API – что это такое простыми словами: примеры использования функционала

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

Где используются API-технологии

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

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

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

Основной функционал API

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

Принцип работы механизма API состоит в организации многоуровневой иерархии, в которой подчинённые компоненты создаются с одинаковой структурой. Выстраивается стандартная сетевая модель OSI с определённым количеством ступеней (не менее 7). Внутренние уровни классифицируются, выделяют приложения HTTP, IMAP, физические уровни трансляции и пр. Такое построение позволяет использовать в интерфейсе функционал нижних API для работы верхних.

Для эффективной организации работы создаются библиотеки функций и классов с описанием сигнатур и семантики. Сигнатура в данном случае является частью объявления функции, которая идентифицирует элемент. Её можно представить с помощью различных языков программирования и определить возможности перезагрузки. Описывая языки вызова, специалисты разделяют сигнатуры вызова и реализации заданных функций. Сигнатуру определяют, учитывая область видимости и последовательностей фактических типов аргументов. Такие компоненты позволяют компилятору распознавать функции при работе с языком С++. Если это метод определённого класса, сигнатуру включают в имя данного класса.

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

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

Типы API

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

Выделяют глобальные продукты с отдельными языками программирования, предназначенные для решения локальных задач. Есть также продукты для управления различными графическими компонентами модулей программ (wxWidgets, Qt, GTK и т. д.), операционными системами (Amiga ROM Kernel, POSIX, Linux Kernel APIruen, Cocoa, OS/2 API, Windows API), звуковыми (DirectMusic/DirectSound, OpenAL), оконными интерфейсами и т. д. Именно графические API предназначены для улучшения яркости и чёткости изображений в компьютерных играх, разных приложениях с качественной визуализацией. Чем сложнее система интерфейса, тем больше вероятность возникновения технических сложностей при работе с приложением. Какие проблемы могут возникать:

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

Кроме того, существует и политика выпуска API, которая определяет степень доступности технологии разным пользователям. Так, выделяют политики:

  • Private — API предназначен только для внутреннего использования;
  • «Партнёр» — это значит, что доступ к технологии предоставляется только отдельным деловым партнёрам;
  • Public — API является публичным и открытым всем.

API поисковых систем и веб-специалистов

Мастера, которые занимаются программированием и оформлением сайтов, а также их продвижением, используют специальный Web API. Это интерфейсы, которые включают комплект определённых HTTP-запросов. При получении такого рода запросов модуль генерирует HTTP-ответы определённой структуры. Чтобы передавать информацию, между ними применяются форматы XML или JSON. В этой сфере применения Web API является синонимом веб-службы, определёнными программами с соответствующими интерфейсами. Чтобы получить доступ к данным модулям, нужно пройти процедуру идентификации в Интернете по онлайн-адресу. То есть при необходимости передачи данных на сервер нужно использовать серверный модуль взаимодействия с API.

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

Одним из примеров API в интернет-рекламе является приложение, которое использует «Яндекс.Директ». Для настройки и более эффективного управления рекламными кампаниями создаются специальные модули, которые позволяют улучшить параметры поисковой оптимизации (SEO) путём информационного взаимодействия.

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

При подборе оптимального приложения веб-мастерам нужно учитывать изменения, которые наблюдаются после массового применения стандартов Web 2.0. Нововведения касались протоколов обмена структурированных данных в SOAP (распределение в вычислительной среде, касающееся доступа к объектам). Эти протоколы были приведены к упрощённому архитектурному стилю. Для интернет-магазинов и других онлайн-ресурсов с большим объёмом информации это дало возможность ускорить процессы выполнения заданных действий. Таким образом, разработчик при подборе приложения определяет, какой именно интерфейс необходимо применить для автоматизации всех основных процессов.

Отдельные компоненты системы взаимодействуют между собой по аналогии связей серверов и пользователей сети Интернет. Несмотря на отсутствие единых стандартов, системы на базе архитектуры REST реализуются с применением классических моделей HTTP, URL, JSON и XML. Такой подход обеспечивает возможность дополнений и расширений функциональности приложений.

Теги термина


Голосов 8, рейтинг 4.5

что это такое и зачем нужны технологии SEO API для сайта, интерфейс и функция


API (application programming interface) — это набор готовых классов, функций, процедур, структур и констант. Вся эта информация предоставляется самим приложением (или операционной системой). При этом пользователю не обязательно понимать, что это API технология обеспечивает взаимодействие модулей. Цель предоставленной информации – использование этих данных при взаимодействии с внешними программами.


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


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

Функции API


В процессе работы элементы механизма API организуют многоуровневую иерархию. При этом подчиненные компоненты также получают подобную структуру. Внутри стандартной сетевой модели OSI выделяют как минимум 7 внутренних уровней. Они классифицируются от физического уровня трансляции бит до приложений, таких как протоколы HTTP и IMAP. Таким образом API верхнего использует функциональность нижнего.


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


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


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


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


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

Типы API


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


В отдельные группы выделяют интерфейсы управления графическими компонентами программных модулей (API графических интерфейсов wxWidgets, Qt, GTK и т. п.), операционными системами (Amiga ROM Kernel, Cocoa, Linux Kernel APIruen, OS/2 API, POSIX, Windows API), звуковые (DirectMusic/DirectSound, OpenAL), оконные интерфейсы и так далее. Здесь их разделение определяется уровнем приложения в иерархии и функциональностью. Пользователи компьютерных игр обычно не подозревают, что это графический API обеспечивает им такую быструю отрисовку картинки и поразительную яркость изображений.


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


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

  1. Трудности портирования кода программы при переходе от одной API к другой. Они часто появляются при переносе модулей в другие операционные системы.
  2. Снижения объема функциональности интерфейса при переходе к управлению с более низкого уровня на высокий. В этом случае облегчается выполнение строго определенного класса задач. При этом возможности доступа к элементам управления другими регуляторами теряются. Ведь более низкий уровень позволяет легко управлять базовыми компонентами программы.

API вебмастеров / поисковых систем


Для вебмастеров и программистов особенно важны Web API. Такие системы управления включают в себя комплект HTTP-запросов. В результате получения таких запросов модуль генерирует строго определенную структуру HTTP-ответов. Для транспортировки информации между ними принято использовать форматы XML или JSON.


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


В случае построения программных систем на основе сервис-ориентированной архитектуры именно веб-служба является уровнем формирования модулей.


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


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


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


Обычно порядок работы интерфейса стараются передать в его названии. Мы можем не найти в поиске, что такое syngestureapisampleapp application. Но из названия понятно, что это пример работы интерфейса для единичного пользователя.


При этом нужно учитывать изменения в интерфейсах, произошедшие после массового внедрения стандартов Web 2.0. В результате был выполнен переход протокола обмена структурированными данными в распределенной вычислительной среде SOAP (от англ. Simple Object Access Protocol — простой протокол доступа к объектам) к архитектурному стилю взаимодействия компонентов распределенного приложения в сети REST (сокр. от англ. Representational State Transfer — «передача состояния представления»). Для многих веб-служб, в число которых входят поисковые системы и интернет-магазины, данный переход привел к упрощению архитектуры и ускорению выполнения задач. Правильная организация информационных потоков приводит к тому, что API сайта предоставляет широкие возможности автоматизации последнего.


При этом отдельные компоненты REST функционируют примерно таким же образом, как взаимодействуют между собой серверы и клиенты в Интернете. Хотя работа систем на архитектуре REST до сих пор не имеет единого стандарта, большинство RESTful-реализаций используют конкретные стандарты, такие как HTTP, URL, JSON и XML. Здесь особенно важно, что открытый API – это возможность дополнения и расширения системы взаимодействия.

данных запроса с использованием веб-API (Common Data Service) — Power Apps

  • 8 минут на чтение

В этой статье

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

Пример базового запроса

В этом примере запрашивается набор сущностей учетных записей и используются параметры системного запроса $ select и $ top для возврата свойства имени для первых трех учетных записей:

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ top = 3 HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (name)",
   "ценность":[
      {
         "@ odata.etag": "W / \" 501097 \ "",
         "name": "Четвертый кофе (образец)",
         "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
      },
      {
         "@ odata.etag": "W / \" 501098 \ "",
         "name": "Litware, Inc. (образец)",
         "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
      },
      {
         "@odata.etag ":" W / \ "501099 \" ",
         "name": "Приключенческие произведения (образец)",
         "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
      }
   ]
}
 
  

Ограничения на количество возвращаемых сущностей

Если вы не укажете меньший размер страницы, для каждого запроса будет возвращено не более 5000 объектов. Если есть другие объекты, соответствующие критериям фильтра запроса, с результатами будет возвращено свойство @ odata.nextLink . Используйте значение свойства @ odata.nextLink с новым запросом GET , чтобы вернуть следующую страницу данных.

Использовать опцию запроса $ top

Вы можете ограничить количество результатов, возвращаемых с помощью параметра системного запроса $ top . В следующем примере будут возвращены только первые три объекта учетной записи.

  GET [URI организации] /api/data/v9.1/accounts?$select=name,revenue&$top=3
  

Примечание

Ограничение результатов с использованием $ top предотвратит применение предпочтения odata.maxpagesize . Вы можете использовать odata.maxpagesize или $ top , но не то и другое одновременно. Дополнительные сведения о odata.maxpagesize см. В разделе Определение числа объектов, возвращаемых на странице.

Вы также не должны использовать $ top с $ count .

Укажите количество объектов, возвращаемых на странице

Используйте значение предпочтения odata.maxpagesize , чтобы запросить количество объектов, возвращенных в ответе.

Примечание

Вы не можете использовать odata.maxpagesize значение предпочтения больше 5000.

В следующем примере запрашивается набор сущностей учетных записей и возвращается свойство name для первых трех учетных записей.

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
Предпочитайте: odata.maxpagesize = 3
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
Длина содержимого: 402
Применено предпочтение: odata.maxpagesize = 3
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (name)",
   "ценность":[
      {
         "@ odata.etag": "W / \" 437194 \ "",
         "name": "Четвертый кофе (образец)",
         "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
      },
      {
         "@ odata.etag": "W / \" 437195 \ "",
         "name": "Litware, Inc. (образец)",
         "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
      },
      {
         "@odata.etag ":" W / \ "468026 \" ",
         "name": "Приключенческие произведения (образец)",
         "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
      }
   ],
   "@ odata.nextLink": "[URI организации] /api/data/v9.1/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d % 25221% 2522% 253e% 253caccountid% 2520last% 253d% 2522% 257b8151925C-CDE2-E411-80DB-00155D2A68CB% 257d% 2522% 2520first% 253d% 2522% 257b7D51925C-CD1580% 257b7D51925C-CD158D2-CD2D2-CD2-E202-CD2-E2 % 252f% 253e% 253c% 252fcookie% 253e% 22% 20 /% 3E "
}
  
  

Используйте значение @odata.nextLink для запроса следующего набора записей. Не изменяйте и не добавляйте к значению какие-либо дополнительные параметры системного запроса. Для каждого последующего запроса дополнительных страниц следует использовать то же значение предпочтения odata.maxpagesize, которое использовалось в исходном запросе. Кроме того, кешируйте возвращенные результаты или значение свойства @ odata.nextLink , чтобы можно было вернуть ранее полученные страницы.

Примечание

Значение свойства @ odata.nextLink закодировано в URI.Если вы кодируете значение URI перед его отправкой, информация XML-файла cookie в URL-адресе вызовет ошибку.

Применить параметры запроса системы

Каждый из параметров системного запроса, который вы добавляете к URL-адресу для набора сущностей, добавляется с использованием синтаксиса для строк запроса. Первый добавляется после [?], А последующие параметры запроса разделяются с помощью [&]. Все параметры запроса чувствительны к регистру, как показано в следующем примере.

  GET [URI организации] / api / data / v9.1 / account? $ Select = name, доход
& $ top = 3
& $ filter = доход gt 100000
  

Запросить особые свойства

Используйте параметр системного запроса $ select , чтобы ограничить возвращаемые свойства, как показано в следующем примере.

  GET [URI организации] /api/data/v9.1/accounts?$select=name,revenue
  

Важно

Это лучший метод производительности. Если свойства не указаны с помощью $ select , будут возвращены все свойства.

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

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

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

Фильтровать результаты

Используйте опцию системного запроса $ filter , чтобы задать критерии, по которым будут возвращаться объекты.

Операторы стандартных фильтров

Веб-API поддерживает стандартные операторы фильтра OData, перечисленные в следующей таблице.

Оператор Описание Пример
Операторы сравнения
экв равно $ filter = экв. Дохода 100000
ne Не равно $ filter = выручка ne 100000
GT Больше $ filter = выручка gt 100000
ge Больше или равно $ filter = доход ge 100000
л Менее $ filter = выручка lt 100000
le Меньше или равно $ filter = le выручка 100000
Логические операторы
и логический и $ filter = доход lt 100000 и доход gt 2000
или логический или $ filter = contains (name, '(sample)') или contains (name, 'test')
не Логическое отрицание $ filter = не содержит (имя, 'образец')
Операторы группировки
() Группировка по приоритету (содержит (имя, 'образец') или содержит (имя, 'тест')) и доход gt 5000

Стандартные функции запросов

Веб-API поддерживает следующие стандартные функции строкового запроса OData:

Функция Пример
содержит $ filter = contains (name, '(sample)')
заканчивается с $ filter =ndswith (name, 'Inc.')
начинается с $ filter = начинается с (имя, 'a')

Функции запросов веб-API Common Data Service

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

  GET [URI организации] /api/data/v9.1/accounts?$select=name,numberofemployees
& $ filter = Microsoft.Dynamics.CRM.Between (PropertyName = 'numberofemployees', PropertyValues ​​= ["5", "2000"])
  

Дополнительная информация: Составьте запрос с функциями.

Использовать лямбда-операторы

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

любой оператор

Оператор any возвращает true , если примененное логическое выражение имеет значение true для любого члена коллекции, в противном случае он возвращает false .Оператор any без аргумента возвращает true , если коллекция не пуста.

Пример

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

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = Account_Emails / any (o: contains (o / subject, 'sometext')) HTTP / 1.1
Предпочитаю: odata.include-annotations = "*"
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

все оператор

Оператор all возвращает true , если примененное логическое выражение имеет значение true для всех членов коллекции, в противном случае он возвращает false .

Пример

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

  GET [URI организации] / api / data / v9.1 / аккаунты? $ Select = name
& $ filter = Account_Tasks / all (o: o / statecode eq 1) HTTP / 1.1
Предпочитаю: odata.include-annotations = "*"
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

В приведенном ниже примере показано, как можно получить все записи сущностей Account, которые имеют хотя бы одно электронное письмо с «sometext» в теме и чей код состояния активен.

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = Account_Emails / any (o: contains (o / subject, 'sometext') и
o / statecode eq 0) HTTP / 1.1
Предпочитаю: odata.include-annotations = "*"
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

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

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = (contact_customer_accounts / any (c: c / jobtitle eq 'jobtitle' и
c / possible_customer_contacts / any (o: o / description ne 'N / A'))) и
заканчивается (имя, '{0}') HTTP / 1.1
Предпочитаю: odata.include-annotations = "*"
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Фильтрация родительских записей на основе значений дочерних записей

В приведенном ниже примере показано, как можно использовать оператор / any для получения всех записей учетной записи, в которых есть:

  • бюджет любой из связанных записей возможностей больше или равен 300, и
  • записи возможности не имеют описания, или
  • описание записей возможности содержит термин « плохой ».

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = not possible_customer_accounts / any (o: o / description eq null и
o / budgetamount le 300 или
содержит (o / description, 'bad')) и
possible_customer_accounts / any () и
заканчивается (имя, '{0}') HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Фильтрация записей на основе однозначного свойства навигации

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

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

Например:

  • Получить все совпадающие учетные записи для указанного идентификатора контакта

Запрос

  GET [URI организации] / api / data / v9.1 / аккаунты? $ Select = name
& $ filter = primarycontactid / contactid eq a0dbf27c-8efb-e511-80d2-00155db07c77 HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
  
{
"@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (name)",
"ценность":[
        {
            "@ odata.etag": "W / \" 513479 \ "",
            "name": "Приключенческие произведения (образец)",
            "accountid": "3adbf27c-8efb-e511-80d2-00155db07c77"
        },
        {
            "@odata.etag ":" W / \ "514057 \" ",
            "name": "Blue Yonder Airlines (образец)",
            "accountid": "3edbf27c-8efb-e511-80d2-00155db07c77"
        }
    ]
}
  
  • Получить дочерние учетные записи для указанного идентификатора учетной записи

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = parentaccountid / accountid eq 3adbf27c-8efb-e511-80d2-00155db07c77
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
  
{
"@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (name)",
"ценность":[
        {
            "@ odata.etag": "W / \" 514058 \ "",
            "name": "Образец дочернего аккаунта 1",
            "accountid": "915e89f5-29fc-e511-80d2-00155db07c77"
        },
        {
            "@ odata.etag": "W / \" 514061 \ "",
            "name": "Образец дочернего аккаунта 2",
            "accountid": "03312500-2afc-e511-80d2-00155db07c77"
        }
    ]
}
  

Фильтрация результатов на основе значений свойств навигации, оценивающих коллекцию

Примечание

Можно использовать $ filter в пределах $ expand для фильтрации результатов для связанных записей в операции Retrieve.Вы можете использовать список параметров системного запроса, разделенный точкой с запятой, заключенный в круглые скобки после имени свойства навигации, имеющего значение коллекции. Параметры запроса, которые поддерживаются в пределах $ expand : $ select , $ filter , $ top и $ orderby . Дополнительная информация: Параметры, применяемые к развернутым объектам.

Два варианта фильтрации результатов на основе значений свойств навигации, оценивающих коллекцию:

  1. Создание запроса с использованием лямбда-операторов

Лямбда-операторы позволяют применять фильтр к значениям свойств коллекции для объекта ссылки.В приведенном ниже примере извлекаются записи типа сущности systemuser , которые связаны с типами сущностей team и teammembership , это означает, что он извлекает записи systemuser , которые также являются администраторами группы с именем «CITTEST».

  GET [URI организации] /api/data/v9.1/systemusers?$filter= (teammembership_association / any (t: t / name eq 'CITTEST'))
& $ select = fullname, businessunitid, title, address1_telephone1, systemuserid
& $ orderby = полное имя
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Дополнительная информация: используйте лямбда-операторы.

  1. Итерация результатов, фильтрация отдельных сущностей на основе значений в коллекции с использованием нескольких операций

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

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

  1. Получите отдельный список значений team._administratorid_value.
    • GET [OrganizationURI] /api/data/v9.1/teams?$select=_administratorid_value&$filter=_administrator_value ne null
    • Затем переберите возвращенные значения, чтобы удалить дубликаты и получить отдельный список. т.е. создайте новый массив, переберите результаты запроса для каждой проверки, чтобы увидеть, есть ли они уже в новом массиве, если нет, добавьте их.Это должно дать вам список различных systemuserid значений
    • То, как вы это сделаете в JavaScript и C #, будет другим, но по сути вы должны иметь возможность получить те же результаты.
  2. Запрос системного пользователя с помощью функции запроса ContainValues ​​для сравнения значений systemuserid со списком, собранным на шаге 1.

Результаты заказа

Укажите порядок, в котором возвращаются товары, с помощью параметра системного запроса $ orderby .Используйте суффикс asc или desc , чтобы указать порядок возрастания или убывания соответственно. По умолчанию используется возрастание, если суффикс не применяется. В следующем примере показано получение свойств имени и дохода учетных записей, упорядоченных по возрастанию дохода и по убыванию имени.

  GET [URI организации] /api/data/v9.1/accounts?$select=name,revenue
& $ orderby = доход по возрастанию, имя по убыванию
& $ filter = доход ne null
  

Сводные и групповые результаты

Используя $ apply , вы можете динамически агрегировать и группировать данные.Возможные варианты использования с $ применить :

Пример использования Пример
Список уникальных статусов в запросе аккаунтов? $ Apply = groupby ((statuscode))
Совокупная сумма оценочной стоимости возможностей? $ Применить = совокупное (оценочное значение с общей суммой)
Средний размер сделки на основе оценочной стоимости и статуса возможностей? $ Apply = groupby ((код состояния), aggregate (оценочное значение со средним значением в качестве среднего)
Сумма оценочной стоимости на основе статуса возможностей? $ Apply = groupby ((код состояния), aggregate (оценочное значение с суммой как итог))
Общий возможный доход по имени счета возможностей? $ Apply = groupby ((parentaccountid / name), aggregate (приблизительное значение с суммой как итог))
Имена основных контактных лиц для аккаунтов в WA учетных записей? $ Apply = filter (address1_stateorprovince eq 'WA') / groupby ((primarycontactid / fullname))
Дата и время последней созданной записи аккаунтов? $ Apply = aggregate (создано с максимальным значением lastCreate)
Дата и время первой записи аккаунтов? $ Apply = aggregate (создано с min как firstCreate)

Агрегатные функции ограничены набором из 50 000 записей.Дополнительную информацию об использовании агрегатных функций с Common Data Service можно найти здесь: Используйте FetchXML для создания запроса.

Дополнительные сведения об агрегировании данных OData можно найти здесь: Расширение OData для агрегирования данных версии 4.0. Обратите внимание, что Common Data Service поддерживает только подмножество этих агрегированных методов.

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

Вы можете использовать псевдонимы параметров для параметров системного запроса $ filter и $ orderby .Псевдонимы параметров позволяют использовать одно и то же значение несколько раз в запросе. Если псевдониму не присвоено значение, предполагается, что он равен нулю.

Без псевдонимов параметров:

  GET [URI организации] /api/data/v9.1/accounts?$select=name,revenue
& $ orderby = доход по возрастанию, имя по убыванию
& $ filter = доход ne null
  

С псевдонимами параметров:

  GET [URI организации] /api/data/v9.1/accounts?$select=name,revenue
& $ orderby = @ p1 asc, @ p2 desc
& $ filter = @ p1 ne @ p3 & @ p1 = доход & @ p2 = name
  

Вы также можете использовать псевдонимы параметров при использовании функций.Дополнительная информация: Использование функций веб-API

Получить количество объектов

Используйте параметр системного запроса $ count со значением true , чтобы включить количество сущностей, соответствующих критериям фильтра, вплоть до 5000.

Свойство response @ odata.count будет содержать количество объектов, которые соответствуют критериям фильтра, независимо от ограничения предпочтения odata.maxpagesize .

Примечание

Не следует использовать $ top с $ count .

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

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name
& $ filter = contains (имя, 'образец')
& $ count = true HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
Предпочитайте: odata.maxpagesize = 3
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
Применено предпочтение: odata.maxpagesize = 3
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (name)",
   "@ odata.count": 10,
   "ценность":[
      {
         "@ odata.etag": "W / \" 502482 \ "",
         "name": "Четвертый кофе (образец)",
         "accountid": "655eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {
         "@ odata.etag": "W / \" 502483 \ "",
         "name": "Litware, Inc. (образец)",
         "accountid": "675eaf89-f083-e511-80d3-00155d2a68d3"
      },
      {
         "@odata.etag ":" W / \ "502484 \" ",
         "name": "Приключенческие произведения (образец)",
         "accountid": "695eaf89-f083-e511-80d3-00155d2a68d3"
      }
   ],
   "@ odata.nextLink": "[URI организации] /api/data/v9.1/accounts?$select=name&$filter=contains (name, 'sample') & $ skiptoken =% 3Cookie% 20pagenumber =% 222% 22% 20pagingcookie =% 22% 253ccookie% 2520page% 253d% 25221% 2522% 253e% 253caccountid% 2520last% 253d% 2522% 257b695EAF89-F083-E511-80D3-00155D2A68D3% 257dirst% 253bdirst% 253d5E2522% 253 -E511-80D3-00155D2A68D3% 257d% 2522% 2520% 252f% 253e% 253c% 252fcookie% 253e% 22% 20istracking =% 22False% 22% 20 /% 3E "
}

  
  

Если вы не хотите возвращать какие-либо данные, кроме счетчика, вы можете применить $ count к любой коллекции, чтобы получить только значение.

Запрос

  GET [URI организации] /api/data/v9.1/accounts/$count HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: текст / простой
OData-Версия: 4.0
  
10
  

Включить форматированные значения

Если вы хотите получить форматированные значения для свойств с результатами, используйте предпочтение odata.include-annotations со значением OData.Community.Display.V1.FormattedValue . Ответ будет включать эти значения со свойствами, соответствующими следующему соглашению об именах:

   @ OData.Community.Display.V1.FormattedValue
  

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

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$select=name,donotpostalmail,accountratingcode, numberofemployees ,revenue
& $ top = 1 HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
Предпочтительно: odata.include-annotations = "OData.Community.Display.V1.FormattedValue"
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
Применяемые предпочтения: odata.include-annotations = "OData.Community.Display.V1.FormattedValue"
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (имя, donotpostalmail, accountratingcode, количество сотрудников, доход)",
   "ценность":[
      {
         "@odata.etag ":" W / \ "502170 \" ",
         "name": "Четвертый кофе (образец)",
         "[email protected]": "Разрешить",
         "donotpostalmail": ложь,
         "[email protected]": "Значение по умолчанию",
         "accountratingcode": 1,
         "[email protected]": "9,500",
         «количество сотрудников»: 9500,
         "доход@OData.Community.Display.V1.FormattedValue": "100 000,00 долларов США",
         «выручка»: 100000,
         "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
         "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1"
      }
   ]
}
  

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

Получить данные о свойствах поиска

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

Для этих свойств доступны два дополнительных типа аннотаций:

Аннотация Описание
Microsoft.Dynamics.CRM.associatednavigationproperty Имя однозначного свойства навигации, которое включает ссылку на сущность.
Microsoft.Dynamics.CRM.lookuplogicalname Логическое имя объекта, на который ссылается поиск.

Эти свойства также могут включать отформатированные значения, как описано в разделе «Включить отформатированные значения». Как и отформатированные значения, вы можете вернуть другие аннотации, используя предпочтение odata.include-annotations , установленное для определенного типа аннотации, которое вы хотите, или вы можете установить значение "*" и вернуть все три. В следующем примере показаны запрос и ответ для получения информации о свойстве поиска объекта _customerid_value объекта инцидента с включенными аннотациями.

Запрос

  GET [URI организации] /api/data/v9.1/incidents (39dd0b31-ed8b-e511-80d2-00155d2a68d4)? $ Select = title, _customerid_value
& $ expand = customerid_contact ($ select = fullname) HTTP / 1.1
Принять: приложение / json
Тип содержимого: приложение / json; charset = utf-8
OData-Max Версия: 4.0
OData-Версия: 4.0
Предпочитаю: odata.include-annotations = "*"
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; одата.метаданные = минимальные
OData-Версия: 4.0
Применяемые предпочтения: odata.include-annotations = "*"
  
{
    "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#incidents (title, _customerid_value, customerid_contact (полное имя)) / $ entity",
    "@ odata.etag": "W / \" 504696 \ "",
    "[email protected]perty": "customerid_contact",
    "[email protected]": "контакт",
    "[email protected]": "Susanna Stubberod (образец)",
    "_customerid_value": "7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
    "incidentid": "39dd0b31-ed8b-e511-80d2-00155d2a68d4",
    "customerid_contact": {
        "@odata.etag ":" W / \ "503587 \" ",
        "полное имя": "Сюзанна Стубберод (образец)",
        "contactid": "7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
    }
}
  

Получение связанных сущностей путем расширения свойств навигации, оценивающих коллекцию

Если вы развернете оценивающие коллекцию параметры навигации для извлечения связанных сущностей для наборов сущностей, для связанных сущностей будет возвращено свойство @ odata.nextLink . Вы должны использовать значение свойства @ odata.nextLink с новым запросом GET для возврата требуемых данных.

В следующем примере извлекаются задачи, назначенные для первых 5 записей учетной записи.

Запрос

  GET [URI организации] /api/data/v9.1/accounts?$top=5
& $ select = имя
& $ expand = Account_Tasks ($ select = subject, schedulestart) HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (имя, Account_Tasks, Account_Tasks (тема, запланированное начало))",
   "ценность":[
      {
         "@ odata.etag": "W / \" 513475 \ "",
         "name": "Четвертый кофе (образец)",
         "accountid": "36dbf27c-8efb-e511-80d2-00155db07c77",
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (36dbf27c-8efb-e511-80d2-00155db07c77) / Account_Tasks? $ Select = subject, schedulestart"
      },
      {
         "@odata.etag ":" W / \ "513477 \" ",
         "name": "Litware, Inc. (образец)",
         "accountid": "38dbf27c-8efb-e511-80d2-00155db07c77",
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (38dbf27c-8efb-e511-80d2-00155db07c77) / Account_Tasks? $ Select = subject, schedulestart"
      },
      {
         "@ odata.etag": "W / \" 514074 \ "",
         "name": "Приключенческие произведения (образец)",
         "accountid": "3adbf27c-8efb-e511-80d2-00155db07c77",
         "Account_Tasks": [

         ],
         "Account_Tasks @ odata.nextLink ":" [URI организации] /api/data/v9.1/accounts (3adbf27c-8efb-e511-80d2-00155db07c77) / Account_Tasks? $ select = subject, schedulestart "
      },
      {
         "@ odata.etag": "W / \" 513481 \ "",
         "name": "Fabrikam, Inc. (образец)",
         "accountid": "3cdbf27c-8efb-e511-80d2-00155db07c77",
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (3cdbf27c-8efb-e511-80d2-00155db07c77) / Account_Tasks? $ Select = subject, schedulestart"
      },
      {
         "@odata.etag ":" W / \ "514057 \" ",
         "name": "Blue Yonder Airlines (образец)",
         "accountid": "3edbf27c-8efb-e511-80d2-00155db07c77",
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (3edbf27c-8efb-e511-80d2-00155db07c77) / Account_Tasks? $ Select = subject, schedulestart"
          }
       ]
    }
 
  

Получение связанных сущностей путем расширения свойств навигации как с однозначными, так и с коллекционными значениями

В следующем примере показано, как можно развернуть связанные сущности для наборов сущностей, используя свойства навигации как с одним, так и с коллекцией значений.Как объяснялось ранее, расширение свойств навигации, оценивающих коллекцию, для извлечения связанных сущностей для наборов сущностей, возвращает свойство @ odata.nextLink для связанных сущностей. Вы должны использовать значение свойства @ odata.nextLink с новым запросом GET для возврата требуемых данных.

В этом примере мы получаем контакт и задачи, назначенные трем основным учетным записям.

Запрос

  GET [URI организации] / api / data / v9.1 / аккаунтов? $ Top = 3
& $ select = имя
& $ expand = primarycontactid ($ select = contactid, fullname), Account_Tasks ($ select = subject, schedulestart) HTTP / 1.1
Принять: приложение / json
OData-Max Версия: 4.0
OData-Версия: 4.0
  

Ответ

  HTTP / 1.1 200 ОК
Тип содержимого: приложение / json; odata.metadata = минимальный
OData-Версия: 4.0
  
{
   "@ odata.context": "[URI организации] /api/data/v9.1/$metadata#accounts (имя, primarycontactid, Account_Tasks, primarycontactid (contactid, полное имя), Account_Tasks (тема, запланированное начало))",
   "ценность":[
      {
         "@odata.etag ":" W / \ "550614 \" ",
         "name": "Четвертый кофе (образец)",
         "accountid": "5b9648c3-68f7-e511-80d3-00155db53318",
         "primarycontactid": {
            "contactid": "c19648c3-68f7-e511-80d3-00155db53318",
            "полное имя": "Ивонн МакКей (образец)"
         },
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (5b9648c3-68f7-e511-80d3-00155db53318) / Account_Tasks? $ Select = subject, schedulestart"
      },
      {
         "@odata.etag ":" W / \ "550615 \" ",
         "name": "Litware, Inc. (образец)",
         "accountid": "5d9648c3-68f7-e511-80d3-00155db53318",
         "primarycontactid": {
            "contactid": "c39648c3-68f7-e511-80d3-00155db53318",
            "полное имя": "Сюзанна Стубберод (образец)"
         },
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (5d9648c3-68f7-e511-80d3-00155db53318) / Account_Tasks? $ Select = subject, schedulestart"
      },
      {
         "@odata.etag ":" W / \ "550616 \" ",
         "name": "Приключенческие произведения (образец)",
         "accountid": "5f9648c3-68f7-e511-80d3-00155db53318",
         "primarycontactid": {
            "contactid": "c59648c3-68f7-e511-80d3-00155db53318",
            "полное имя": "Нэнси Андерсон (образец)"
         },
         "Account_Tasks": [

         ],
         "[email protected]": "[URI организации] /api/data/v9.1/accounts (5f9648c3-68f7-e511-80d3-00155db53318) / Account_Tasks? $ Select = subject, schedulestart"
      }
   ]
}
  
  

Использование отслеживания изменений для синхронизации данных с внешними системами

Функция отслеживания изменений позволяет эффективно поддерживать синхронизацию данных, определяя, какие данные были изменены с момента первоначального извлечения данных или последней синхронизации.Изменения, внесенные в сущности, можно отслеживать с помощью запросов веб-API, добавляя odata.track-changes в качестве заголовка предпочтения. Заголовок предпочтения odata.track-changes запрашивает возврат дельта-ссылки, которая впоследствии может использоваться для получения изменений объекта.

Дополнительная информация: Используйте отслеживание изменений для синхронизации данных с внешними системами.

Сравнение столбцов с использованием веб-API

В следующем примере показано, как сравнить столбцы с помощью веб-API:

  https: //  / contacts? $ Select = firstname & $ filter = firstname eq lastname
  

Дополнительная информация: Использование сравнения столбцов в запросах

См. Также

Работа с ограничением элементов поиска для быстрого поиска
Образец данных запроса веб-API (C #)
Образец данных запроса веб-API (клиентский JavaScript)
Выполнение операций с использованием веб-API
Составление запросов Http и обработка ошибок
Создание объекта с помощью Интернета API
Извлечение сущности с помощью веб-API
Обновление и удаление сущностей с помощью веб-API
Связывание и разъединение сущностей с помощью веб-API
Использование функций веб-API
Использование действий веб-API
Выполнение пакетных операций с использованием веб-API
Выдача себя за другого пользователя с помощью веб-API
Выполнять условные операции с помощью веб-API

.

типов и операций веб-API (Common Data Service) — Power Apps

  • 8 минут на чтение

В этой статье

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

Терминология

Веб-API реализован с использованием стандарта OData v4, который использует определенный набор терминов, с которыми вам необходимо ознакомиться. Entity Data Model (EDM) — это абстрактная модель данных, которая используется для описания данных, предоставляемых службой OData.В следующей таблице представлен избранный список терминов, определенных в OData версии 4.0, часть 1: Протокол плюс исправления 02, которые вы должны понимать.

.

Срок Определение
Типы организаций Именованные структурированные типы с ключом. Они определяют именованные свойства и отношения объекта. Типы сущностей могут быть производными путем однократного наследования от других типов сущностей.
Объекты Экземпляры типов сущностей (например,г. счет, возможность).
Наборы сущностей Именованные коллекции сущностей (например, учетные записи — это набор сущностей, содержащий сущности учетных записей). Ключ объекта однозначно идентифицирует объект в наборе объектов
Сложные типы Именованные структурированные типы без ключа, состоящие из набора свойств. Сложные типы обычно используются как значения свойств в сущностях модели или как параметры или возвращаемые значения для операций.
Типы перечисления или Типы перечисления Именованные примитивные типы, значения которых являются именованными константами с соответствующими целочисленными значениями.
Функции Операции, которые не имеют побочных эффектов и могут поддерживать дальнейшую композицию, например, с дополнительными операциями фильтрации, функциями или действием
Действия Операции, которые допускают побочные эффекты, такие как изменение данных, и не могут быть дополнительно скомпонованы, чтобы избежать недетерминированного поведения

Сервисные документы

Есть два служебных документа, на которые вы можете ссылаться, чтобы узнать больше о веб-API.

Сервисный документ

Следующий запрос, введенный в поле адреса вашего браузера, возвращает служебный документ , полный список всех наборов сущностей, доступных для вашей организации. Обратите внимание, что [URI организации] представляет собой URL-адрес вашей организации.

 
[URI организации] /api/data/v9.0
  
  

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

Объект Описание
название Это имя набора сущностей. Эти данные взяты из свойства EntityMetadata EntityType EntitySetName для сущности.
вид Для веб-API перечислены только наборы сущностей.
URL Это значение совпадает со свойством name и представляет собой часть пути к ресурсу для получения данных для объекта.

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

CSDL $ документ метаданных

Запрос GET по следующему URL-адресу вернет довольно большой (более 3,5 МБ) документ Common Schema Definition Language (CSDL) или документ метаданных , который описывает данные и операции, предоставляемые службой.

  GET [URI организации] / api / data / v9.0 / $ метаданных
  

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

Дополнительные сведения об этом документе см. В OData версии 4.0, часть 3: Common Schema Definition Language (CSDL) Plus Errata 02.

Подсказка

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

Вы можете просмотреть или загрузить документ с помощью браузера, перейдя по URL-адресу.

Аннотации метаданных

Документ метаданных включает несколько типов элементов Аннотации , которые предоставляют дополнительную информацию об элементах метаданных и возможностях службы.Начиная с v9.x, эти аннотации не включаются в документ метаданных по умолчанию, если явно не запрошено. Эти аннотации увеличивают размер документа метаданных и не всегда необходимы.

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

Каждый элемент Annotation включает в себя атрибут Term , который описывает тип аннотации. Определения всех возможных аннотаций, используемых OData v4, можно найти в OData Vocabularies версии 4.0. В следующей таблице приведены некоторые примеры, используемые веб-API.

Срок Описание
Org.OData.Core.V1.Description Описание типа объекта или свойства.
Org.OData.Core.V1.Permissions Список разрешений, доступных для свойства, когда разрешения ограничены. Обычно это появляется для свойств только с одной организацией .OData.Core.V1.PermissionType / Read дочерний элемент, чтобы указать, что свойство доступно только для чтения.
Org.OData.Core.V1.Computed Вычислено ли свойство. Они также обычно доступны только для чтения.
OData.Community.Keys.V1.AlternateKeys Содержит набор элементов, описывающих любые альтернативные ключи, определенные для объекта. Дополнительная информация: Альтернативные ключи
Орг.OData.Capabilities.V1.IndexableByKey Поддерживает ли набор сущностей значения ключей в соответствии с соглашениями об URL-адресах OData.
Org.OData.Capabilities.V1.SkipSupported Поддерживает ли набор сущностей $ skip .
Org.OData.Capabilities.V1.Search Restrictions Какие ограничения на выражения $ search применяются к набору объектов.
Орг.OData.Capabilities.V1.CountRestrictions Какие ограничения на суффикс пути / $ count и параметр системного запроса $ count = true.
Org.OData.Capabilities.V1.NavigationRestrictions Какие ограничения на переход по свойствам в соответствии с соглашениями об URL-адресах OData.
Org.OData.Capabilities.V1.ChangeTracking Возможности отслеживания изменений этой службы или набора объектов.
Org.OData.Capabilities.V1.ConformanceLevel Уровень соответствия, достигаемый данной услугой.
Org.OData.Capabilities.V1.FilterFunctions Список функций и операторов, поддерживаемых в $ filter .
Org.OData.Core.V1.DereferenceableIDs Указывает, являются ли идентификаторы объектов URL-адресами, определяющими местонахождение идентифицированного объекта.
Орг.OData.Core.V1.ConventionalIDs Соответствуют ли идентификаторы объектов соглашениям об URL-адресах OData.
Org.OData.Capabilities.V1.AsynchronousRequestsSupported Поддерживает ли служба предпочтение асинхронного запроса.
Org.OData.Capabilities.V1.BatchContinueOnErrorSupported Поддерживает ли служба предпочтение «Продолжить при ошибке». Этот параметр поддерживает пакетные запросов на сумму $.
Org.OData.Capabilities.V1.CrossJoinSupported Поддерживаются ли перекрестные соединения для наборов сущностей в этом контейнере.
Org.OData.Capabilities.V1.SupportedFormats Типы носителей поддерживаемых форматов, включая параметры формата.

Типы сущностей

Справочник по веб-API EntityType перечисляет каждый из типов системных сущностей, предоставляемых через веб-API, в которых хранятся бизнес-данные.Тип сущности - это именованный структурированный тип с ключом. Он определяет именованные свойства и отношения объекта. Типы сущностей могут быть производными путем однократного наследования от других типов сущностей. В справочнике EntityType метаданных веб-API перечислены все типы сущностей, используемые для управления системными метаданными. Оба являются типами сущностей, но работа с ними отличается. См. Использование веб-API с метаданными Common Data Service для получения информации об использовании сущностей модели. Каждый тип объекта включен в элемент EntityType в метаданные $ .Ниже приводится определение EntityType учетной записи из метаданных $ с удаленными свойствами и свойствами навигации.

  
  <Ключ>
    
  
  
  

  

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

Информация Описание
Описание Описание объекта.

EntityMetadata EntityType Описание Информация о свойстве включается в элемент EntityType с использованием элемента Annotation со значением атрибута Term Org.OData.Core.V1. Описание.

Коллекция URL URL-адрес для доступа к коллекции каждого типа.

Информация о свойстве EntityMetadata EntityType EntitySetName включается с помощью элемента $ metadata EntityContainer . Атрибут Name каждого элемента EntitySet управляет доступом к данным через URL.

Базовый тип Это тип сущности, от которого наследуется тип сущности.

Атрибут BaseType элемента EntityType содержит имя типа объекта. Это имя имеет префикс с псевдонимом для пространства имен Microsoft.Dynamics.CRM: mscrm. Подробнее: Наследование типов

Отображаемое имя Этой информации нет в метаданных $ , она извлекается из свойства EntityMetadata EntityType DisplayName .
Первичный ключ Значение свойства, которое содержит уникальный идентификатор для ссылки на экземпляр объекта.

Значение свойства EntityMetadata EntityType PrimaryIdAttribute включено в элемент EntityType Key . У каждой сущности может быть только один первичный ключ.

Альтернативных ключей здесь нет. Дополнительная информация: Альтернативные ключи

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

Этой информации нет в метаданных $ , она извлекается из свойства EntityMetadata EntityType PrimaryNameAttribute метаданных.

Недвижимость См. Свойства.
Однозначные свойства навигации См. Раздел Свойства однозначной навигации.
Навигационная недвижимость коллекционной ценности См. Свойства навигации, связанные с коллекцией.
Операции, привязанные к типу объекта Когда операция привязана к определенному типу объекта, она указывается для удобства.
Операции, использующие вид объекта В этом списке показаны все операции, которые могут использовать этот тип объекта. Это получается путем сбора ссылок на все операции, которые ссылаются на текущий тип в параметрах или как на возвращаемое значение.
Типы сущностей, наследующие от типа сущностей В этот список входят все типы сущностей, которые наследуются непосредственно от типа сущности. Дополнительные сведения см. В разделе «Наследование типов».

Изменить имя набора сущностей

По умолчанию имя набора сущностей соответствует значению свойства EntityMetadata EntityType LogicalCollectionName (EntityMetadata LogicalCollectionName ). Если у вас есть настраиваемая сущность, которую вы хотите адресовать, используя другое имя набора сущностей, вы можете обновить значение свойства EntityMetadata EntityType EntitySetName (EntityMetadata. EntitySetName ), чтобы использовать другое имя.

Альтернативные ключи

Хотя Common Data Service позволяет создавать альтернативные ключи, только первичный ключ будет найден в объектах по умолчанию.

Ни для одного из системных объектов не определены альтернативные ключи. Если вы определите альтернативные ключи для объекта, они будут включены в элемент $ metadata EntityType как аннотация , как показано ниже:

  
  <Коллекция>
    <Тип записи = "OData.Community.Keys.V1.AlternateKey ">
      
        <Коллекция>
          
            
            
          
        
      
    
  

  

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

Наследование типов

Наследование позволяет использовать общие свойства и разбивать типы сущностей на группы. Все типы сущностей в веб-API наследуются от двух из следующих типов сущностей. Все типы бизнес-объектов наследуются от crmbaseentity EntityType, а все объекты модели наследуются от EntityType crmmodelbaseentity.

Недвижимость

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

В элементах $ metadata EntityType каждое свойство включено в элемент Property со значением атрибута Name , которое соответствует свойствам, которые вы зададите в коде.Значение атрибута Type указывает тип данных свойства. Свойства для типов бизнес-объектов обычно используют примитивные типы OData.

Ниже приведен пример свойства учетной записи EntityType name , определенного в метаданных $ .

  
  

  

Описание свойства доступно в элементе Annotation со свойством атрибута Term Org.OData.Core.V1. Описание. Это описание взято из значения свойства AttributeMetadata EntityType Description . Не все свойства имеют описание.

Каждое свойство может быть вычислено. Это означает, что значение может быть установлено системой. Это задается в элементе Annotation со значением атрибута Term Org.OData.Core.V1.Computed.

У каждого свойства также могут быть ограничения на возможность его обновления. Это определено в элементе Annotation со значением атрибута Term Org.OData.Core.V1.Permissions. Для этого установлен единственный параметр - Org.OData.Core.V1.PermissionType / Read, который указывает, что свойство доступно только для чтения.

Примитивные типы

OData

поддерживает широкий спектр типов данных, но Common Data Service не использует их все. В следующей таблице описано, как типы служб Common Data Service Organization сопоставляются с примитивными типами OData.

Организация Тип услуги Веб-API типа Описание
BigInt Edm.Int64 64-битное целое число со знаком
логическое значение Эдм. Булан Двоичная логика
Календарь Правила Однозначные свойства навигации Определенные однозначные свойства навигации для правила EntityType календаря.
Клиент Однозначные свойства навигации Покупатель объекта с этим типом свойства может быть однозначным свойством навигации, установленным либо для учетной записи, либо для типа объекта контакта с использованием соответствующих однозначных свойств навигации.Когда установлено одно из соответствующих однозначных свойств коллекции, другое очищается.
DateTime Edm.DateTimeOffset Дата и время со смещением часового пояса, без дополнительных секунд
В OData нет типа DateTime.
Десятичное Edm. Десятичное Числовые значения с фиксированной точностью и масштабом
Двойной Эдм. Двойной IEEE 754 binary64 число с плавающей запятой (15-17 десятичных цифр)
EntityName Edm.Строка Последовательность символов UTF-8
Изображение Edm. Двоичный Двоичные данные
Целое число Edm.Int32 32-битное целое число со знаком
Поиск Однозначное свойство навигации Ссылка на конкретную организацию
Управляемая недвижимость Не применимо Только для внутреннего использования.
Памятка Edm.Строка Последовательность символов UTF-8
Деньги Edm. Десятичное Числовые значения с фиксированной точностью и масштабом
Владелец Однозначное свойство навигации Ссылка на основной тип EntityType. Типы сущностей systemuser и team наследуют свое свойство ownerid от основного типа сущности.
Список выбора Edm.Int32 32-битное целое число со знаком
Состояние Edm.Int32 32-битное целое число со знаком
Статус Edm.Int32 32-битное целое число со знаком
Строка Edm.String Последовательность символов UTF-8
Уникальный идентификатор Edm.Guid 16-байтовый (128-битный) уникальный идентификатор

Свойства поиска

Для большинства однозначных свойств навигации вы найдете вычисляемое свойство, доступное только для чтения, в котором используется следующее соглашение об именах: _ <имя> _value , где <имя> соответствует имени однозначного свойства навигации.Исключением из этого шаблона является случай, когда атрибут поиска объекта может принимать несколько типов ссылок на объекты. Типичным примером является то, как атрибут объекта объекта customrid может быть установлен на ссылку, которая является либо объектом контакта , либо объектом учетной записи . В свойствах навигации EntityType с одним значением инцидента вы найдете customerid_account и customerid_contact как отдельные свойства навигации с одним значением, чтобы отразить клиента, связанного с возможностью.Если вы установите одно из этих однозначных свойств навигации, для другого будет установлено значение null, поскольку они оба привязаны к атрибуту customerid . В свойствах EntityType инцидента вы найдете свойство поиска _customerid_value , которое содержит то же значение, которое установлено для любого из однозначных свойств навигации, содержащих значение.

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

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

Свойства навигации

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

Однозначные свойства навигации

Эти свойства соответствуют атрибутам поиска, которые поддерживают отношения «многие к одному» и позволяют устанавливать ссылку на другую сущность.В элементе $ metadata EntityType они определены как элемент NavigationProperty с атрибутом Type , установленным для одного типа. Ниже приведен пример учетной записи EntityType , созданной однозначным свойством навигации в метаданных $ :

.

  
 

  

Каждое свойство навигации, представляющее однозначное свойство навигации, будет иметь соответствующее свойство навигации, имеющее значение коллекции, указанное значением атрибута Partner .Каждое однозначное свойство навигации также имеет элемент ReferentialConstraint со значением атрибута Property , который представляет вычисленное свойство поиска только для чтения, которое можно использовать для извлечения соответствующего значения GUID связанной сущности. Дополнительная информация: Свойства поиска

Коллекционная навигационная недвижимость

Эти свойства соответствуют отношениям «один ко многим» или «многие ко многим». В элементе $ metadata EntityType они определены как элемент NavigationProperty с атрибутом Type , установленным для коллекции типа.Следующее представляет учетную запись EntityType Account_Tasks , оценивающую свойство навигации, которое представляет собой отношение «один ко многим»:

  
  

Когда свойство навигации, имеющее значение коллекции, представляет отношение «многие ко многим», имя свойства навигации и имя партнера будут одинаковыми. Следующее представляет учетную запись EntityType accountleads_association возвращающее коллекцию свойство навигации, которое представляет отношение «многие ко многим»:

  
  

Разница между отношениями «один ко многим» и «многие ко многим» не имеет значения при использовании веб-API. Способ связывания объектов одинаков независимо от типа связи. Хотя отношения «многие ко многим» по-прежнему используют сущности пересечения «за кулисами», только несколько специальных сущностей пересечения системы включены в справочник EntityType Web API. Например, entityType кампанииactivityitem технически является объектом пересечения, но он включен, потому что он имеет больше свойств, чем обычный объект пересечения.

Обычный объект пересечения имеет только четыре основных свойства, необходимых для поддержания отношения «многие ко многим». Когда вы создаете настраиваемую связь «многие ко многим» между объектами, будет создана обычная сущность пересечения для поддержки связи. Поскольку вы должны использовать свойства навигации для выполнения операций, связанных с отношениями «многие ко многим», обычные объекты пересечения не документируются, но по-прежнему доступны с использованием веб-API. Эти пересекающиеся типы сущностей доступны с использованием имени набора сущностей, в котором используется следующее соглашение об именах: <логическое имя пересекающейся сущности> + ’collection’.Например, вы можете получить информацию из типа объекта пересечения контактов, используя [URI организации] /api/data/v9.0/contactleadscollection . Эти обычные объекты пересечения следует использовать только в ситуациях, когда вы хотите применить отслеживание изменений.

Действия

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

В разделе «Справочник действий веб-API» перечислены все доступные системные действия.Дополнительная информация: Используйте действия веб-API.

Функции

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

В веб-API определены два типа функций:

Дополнительная информация: Использование функций веб-API

Сложные типы

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

В справочнике

Web API ComplexType перечислены все сложные типы системы. Ниже приведен комплексный тип WhoAmIResponse из метаданных $.

  
  
  
  

  

Перечислимые типы

Перечислимые типы или EnumTypes — это именованные примитивные типы, значения которых являются именованными константами с соответствующими целочисленными значениями.

Web API EnumType Reference перечисляет все типы перечисления системы. Перечислимые типы — это именованные примитивные типы, значения которых называются константами с соответствующими целочисленными значениями. Следующее — это AccessRights EnumType из метаданных $.

  
  
  
  
  
  
  
  Значение 
  
  

  

См. Также

Использование веб-API Common Data Service
Аутентификация в Common Data Service с помощью веб-API
Выполнение операций с использованием веб-API

.

Создание записи сущности с помощью веб-API (Common Data Service) — Power Apps

  • 2 минуты на чтение

В этой статье

Используйте запрос POST для отправки данных для создания объекта. Вы можете создать несколько связанных записей сущностей за одну операцию, используя «глубокую вставку». Вам также необходимо знать, как установить значения, чтобы связать новую запись объекта с существующими объектами с помощью @odata.привязать аннотацию.

Базовое создание

В этом примере создается новая запись сущности счета. Заголовок ответа OData-EntityId содержит Uri созданного объекта.

Запрос

 
POST [URI организации] /api/data/v9.0/accounts HTTP / 1.1
Тип содержимого: приложение / json; charset = utf-8
OData-Max Версия: 4.0
OData-Версия: 4.0
Принять: приложение / json

{
    "name": "Образец учетной записи",
    "creditonhold": ложь,
    "address1_latitude": 47.639583, г.
    "description": "Это описание демонстрационного аккаунта",
    «выручка»: 5000000,
    "accountcategorycode": 1
}
  

Ответ

 
HTTP / 1.1 204 Нет содержимого
OData-Версия: 4.0
OData-EntityId: [URI организации] /api/data/v9.0/accounts (7eb682f1-ca75-e511-80d4-00155d2a68d1)

  

Чтобы создать новую запись объекта, вы должны указать допустимые имена и типы свойств. Для всех системных сущностей и атрибутов вы можете найти эту информацию в теме для этой сущности в Справочнике по сущности.Для настраиваемых сущностей или атрибутов см. Определение этой сущности в документе метаданных CSDL $. Дополнительная информация: Типы сущностей

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

Как и при базовом создании, заголовок ответа OData-EntityId содержит Uri созданного объекта. URI для созданных связанных сущностей не возвращаются.

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

  • Контакт создается, поскольку он определен как свойство объекта однозначного свойства навигации primarycontactid .

  • Возможность создается, потому что она определена как объект в массиве, для которого установлено значение свойства навигации, оцениваемое коллекцией, possible_customer_accounts .

  • Задача создается, потому что она определяется как объект в массиве, для которого установлено значение свойства навигации Opportunity_Tasks , имеющего значение свойства навигации.

Запрос

  POST [URI организации] /api/data/v9.0/accounts HTTP / 1.1
Тип содержимого: приложение / json; charset = utf-8
OData-Max Версия: 4.0
OData-Версия: 4.0
Принять: приложение / json

{
 "name": "Образец учетной записи",
 «первичный контакт»:
 {
     "firstname": "Джон",
     "фамилия": "Смит"
 },
 "possible_customer_accounts":
 [
  {
      "name": "Возможность, связанная с образцом учетной записи",
      «Возможность_Задачи»:
      [
       {"subject": "Задача, связанная с возможностью"}
      ]
  }
 ]
}

  

Ответ

 
HTTP / 1.1 204 Нет содержимого
OData-Версия: 4.0
OData-EntityId: [URI организации] /api/data/v9.0/accounts (3c6e4b5f-86f6-e411-80dd-00155d2a68cb)

  

Связанные записи сущности при создании

Чтобы связать новые объекты с существующими при их создании, вы должны установить значение однозначных свойств навигации с помощью аннотации @ odata.bind .

В следующем теле запроса, отправленном в набор сущностей учетных записей, будет создана новая учетная запись, связанная с существующим контактом со значением contactid 00000000-0000-0000-0000-000000000001.

Запрос

 
POST [URI организации] /api/data/v9.0/accounts HTTP / 1.1
Тип содержимого: приложение / json; charset = utf-8
OData-Max Версия: 4.0
OData-Версия: 4.0
Принять: приложение / json

{
"name": "Образец учетной записи",
"[email protected]": "/ contacts (00000000-0000-0000-0000-000000000001)"
}

  

Ответ

 
HTTP / 1.1 204 Нет содержимого
OData-Версия: 4.0
OData-EntityId: [URI организации] /api/data/v9.0/accounts (00000000-0000-0000-0000-000000000002)

  

Примечание

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

Проверить наличие повторяющихся записей

По умолчанию обнаружение дубликатов отключено, когда вы создаете записи с помощью веб-API. Вы должны включить MSCRM.SuppressDuplicateDetection: false заголовок в свой POST-запрос, чтобы включить обнаружение дубликатов. Обнаружение дубликатов применяется только в том случае, если в организации включено обнаружение дубликатов, для объекта включено обнаружение дубликатов и применяются активные правила обнаружения дубликатов. Дополнительная информация: обнаружение повторяющихся данных с помощью кода

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

Создать новую запись объекта из другого объекта

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

В следующем примере показано, как создать запись учетной записи с использованием значений атрибутов существующей записи сущности учетной записи со значением accountid , равным c65127ed-2097-e711-80eb-00155db75426.

Запрос

  GET [URI организации] / api / data / v9.0 / InitializeFrom (EntityMoniker = @ p1, TargetEntityName = @ p2, TargetFieldType = @ p3)? @ P1 = {'@ odata.id': 'accounts (c65127ed-2097-e711-80eb-00155db75426)'} & @ p2 = 'account'[email protected]=Microsoft.Dynamics.CRM.TargetFieldType'ValidForCreate' HTTP / 1.1
Если-None-Match: нуль
OData-Версия: 4.0
OData-Max Версия: 4.0
Тип содержимого: приложение / json
Принять: приложение / json
  

Ответ

  {
        "@ odata.context": "[URI организации] /api/data/v9.0/$metadata#accounts/$entity",
        "@odata.введите ":" # Microsoft.Dynamics.CRM.account ",
        "[email protected]": "аккаунты (c65127ed-2097-e711-80eb-00155db75426)",
        "[email protected]": "transactioncurrencies (732e87e1-1d96-e711-80e4-00155db75426)",
        "address1_line1": "123 Maple St.",
        "address1_city": "Сиэтл",
        "address1_country": "Соединенные Штаты Америки"
}
  

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

Примечание

Чтобы определить, можно ли сопоставить две сущности, используйте этот запрос:
GET [URI организации] / api / data / v9.0 / entitymaps? $ Select = sourceentityname, targetentityname & $ orderby = sourceentityname

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

  POST [URI организации] /api/data/v9.0/accounts HTTP / 1.1
Тип содержимого: приложение / json; charset = utf-8
OData-Max Версия: 4.0
OData-Версия: 4.0
Принять: приложение / json

    {
        "@ odata.context": "[URI организации] /api/data/v9.0/$metadata#accounts/$entity",
        "@odata.введите ":" # Microsoft.Dynamics.CRM.account ",
        "[email protected]": "аккаунты (c65127ed-2097-e711-80eb-00155db75426)",
        "[email protected]": "transactioncurrencies (732e87e1-1d96-e711-80e4-00155db75426)",
        "name": "Contoso Ltd",
        «количество сотрудников»: «200»,
        "address1_line1": "Кленовая ул., 100",
        "address1_city": "Сиэтл",
        "address1_country": "Соединенные Штаты Америки",
        «факс»: «73737»
    }
}
  

Создать с возвращенными данными

Вы можете составить свой POST-запрос, чтобы данные из созданной записи возвращались со статусом 201 (Создано).Чтобы получить его результат, вы должны использовать предпочтение return = представление в заголовках запроса.

Чтобы указать, какие свойства возвращаются, добавьте параметр запроса $ select к URL-адресу набора сущностей. Параметр запроса $ развернуть будет проигнорирован, если он используется.

Когда объект создается таким образом, заголовок OData-EntityId , содержащий URI для созданной записи, не возвращается.

В этом примере создается новая сущность учетной записи и в ответе возвращаются запрошенные данные.

Запрос

 
POST [URI организации] /api/data/v9.0/accounts?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode, созданный в HTTP / 1.1
OData-Max Версия: 4.0
OData-Версия: 4.0
Принять: приложение / json
Тип содержимого: приложение / json; charset = utf-8
Предпочитаю: возврат = представление

{
   "name": "Образец учетной записи",
   "creditonhold": ложь,
   "address1_latitude": 47.639583,
   "description": "Это описание демонстрационного аккаунта",
   «выручка»: 5000000,
   "accountcategorycode": 1
}

  

Ответ

 
HTTP / 1.1 201 Создано
Тип содержимого: приложение / json; odata.metadata = минимальный
Применяемые предпочтения: return = представление
OData-Версия: 4.0

{
    "@ odata.context": "[URI организации] /api/data/v9.0/$metadata#accounts/$entity",
    "@ odata.etag": "W / \" 536530 \ "",
    "accountid": "d6f193fc-ce85-e611-80d8-00155d2a68de",
    "accountcategorycode": 1,
    "description": "Это описание демонстрационного аккаунта",
    "address1_latitude": 47.63958,
    "creditonhold": ложь,
    "name": "Образец учетной записи",
    "createdon": "2016-09-28T22: 57: 53Z",
    «выручка»: 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

  

См. Также

Пример основных операций веб-API (C #)
Пример основных операций веб-API (клиентский JavaScript)
Функция InitializeFrom
Выполнение операций с использованием веб-API
Создание запросов Http и обработка ошибок
Запрос данных с помощью веб-API
Извлечение объекта с помощью веб-API
Обновление и удаление сущностей с помощью веб-API
Связывание и разъединение сущностей с помощью веб-API
Использование функций веб-API
Использование действий веб-API
Выполнение пакетных операций с использованием веб-API
Выдача себя за другого пользователя с помощью веб-API
Выполнение условного операции с использованием веб-API

.

Watson Data API (бета) — документы IBM Cloud API

Watson Data API (бета)

список опций открытия и закрытия

Обзор

  • Введение
  • Создание токена носителя IAM
  • Управление версиями
  • Сортировка
  • Фильтрация
  • Ограничение скорости
  • Обработка ошибок
  • Подключения
  • Расписания
  • Каталоги
  • Получить каталог
  • Получить каталоги
  • Активы
  • Активы Первичный документ метаданных (или карта)
  • Объекты API других активов
  • Получить актив
  • Создать актив: книга
  • Типы активов
  • Поля типа актива
  • data_asset Type
  • Get Asset Types
  • Get Asset Type: data_asset
  • Create Asset Type: book
  • Search Asset Type: attribute — книга
  • Поиск Тип актива: метаданные — имя
  • Потоки данных
  • Профили данных
  • S tream Flows
  • Обнаружение метаданных
  • Образцы данных
  • Происхождение

Методы

  • Происхождение активов
    • Получение родословных активов
    • Получить сводку родословных активов
  • События происхождения
    • Опубликовать событие происхождения
    • 09 Получить событие происхождения

    • Проекты
      • Создать проект как транзакцию
      • Удалить проект как транзакцию
      • Получить все проекты
      • Получить проект
      • Обновить проект
    • Проекты Участники
      • Получить участников
      • Создать участников
      • Обновить участников
      • Удалить участников
      • Получить участника
      • Удалить участника
    • Типы управления политикой
      • перечислить все типы управления
      • получить тип управления
    • Политики
      • перечислить все политики
      • создать политику
      • количество возвращаемых итогов d активные политики и правила
      • получить политику
      • обновить политику
      • удалить политику
    • категории политики
      • перечислить все категории политики
      • создать категорию политики
      • получить категорию политики
      • обновить категорию политики
      • удалить категорию политики
    • Метрики политики
      • получить и агрегировать метрики, связанные с политикой
    • Правила политики
      • перечислить все правила
      • создать правило
      • получить правило
      • обновить правило
      • удалить правило
      • получить термины, используемые в правиле
    • потоки потоки
      • создать новый поток потоков
      • вернуть список запусков потока потоков
      • вернуть поток потоков
      • удалить поток потоков
      • изменить существующие потоки Flow
    • Streams Flow Runs
      • запуск или остановка S treams Flow
      • возвращает список запусков потока потоков
      • возвращает запуск потока потоков
      • запускает или останавливает поток потоков
    • Business Glossary Imports
      • Создает запрос на импорт, который может быть выполнен.
      • Получает статус импорта.
      • Загружает файл для начала импорта.
      • Запрашивает отмену указанного импорта.
      • Создает отчет с результатами импорта.
      • Выводит статус импортированных терминов для данного идентификатора импорта.
      • Не рекомендуется. Используйте метод GET / v2 / glossary_imports / {guid} / results .
    • Business Glossary Term
      • Добавляет термины в глоссарий.
      • Выполняет поисковый запрос Lucene для заархивированных терминов в глоссарии.
      • Получает заархивированный термин в глоссарии с заданным идентификатором.
      • Очистить заархивированный термин глоссария с заданным идентификатором.
      • Восстанавливает заархивированный термин глоссария с заданным guid.
      • Business Glossary Heartbeat.
      • Выполняет поисковый запрос Lucene для неархивированных терминов в глоссарии.
      • Перечисляет все уникальные теги, которые были применены к терминам глоссария.
      • Получает термин из глоссария с заданным guid.
      • Архивирует или очищает термин глоссария с заданным идентификатором, в зависимости от состояния термина.
      • Обновляет термин в глоссарии.
      • Список ассоциаций данного типа на указанный срок.
      • Получает диапазон правил для данного термина.
      • Показывает количество просмотров для данного термина.
    • Профили данных
      • Список профилей данных
      • Создать профиль данных
    • .

  • Добавить комментарий

    Ваш адрес email не будет опубликован.

    2022 © Все права защищены. Карта сайта