Учебник. Вызов веб-API ASP.NET Core с помощью JavaScript Tutorial: Call an ASP.NET Core web API with JavaScript

В этом руководстве описано, как вызвать веб-API ASP.NET Core с помощью JavaScript и Fetch API. This tutorial shows how to call an ASP.NET Core web API with JavaScript, using the Fetch API.

Если вы используете ASP.NET Core 2.2, см. соответствующий раздел руководства по вызову веб-API с помощью JavaScript. For ASP.NET Core 2.2, see the 2.2 version of Call the web API with JavaScript.

Предварительные требования Prerequisites

• Изучите Учебник. Создание веб-API. Complete Tutorial: Create a web API
• Опыт работы с CSS, HTML и JavaScript. Familiarity with CSS, HTML, and JavaScript

Вызов веб-API с помощью JavaScript Call the web API with JavaScript

В этом разделе описано, как добавить HTML-страницу, содержащую формы для создания и администрирования элементов списка задач. In this section, you’ll add an HTML page containing forms for creating and managing to-do items. Обработчики событий присоединяются к элементам на странице. Event handlers are attached to elements on the page. При использовании обработчиков событий создаются запросы HTTP к методам действия веб-API. The event handlers result in HTTP requests to the web API’s action methods. Функция Fetch API fetch инициирует каждый такой запрос HTTP. The Fetch API’s fetch function initiates each HTTP request.

Функция fetch возвращает объект Promise, который содержит ответ HTTP, представленный в виде объекта Response . The fetch function returns a Promise object, which contains an HTTP response represented as a Response object. Распространенным подходом является извлечение текста ответа JSON путем вызова функции json в объекте Response . A common pattern is to extract the JSON response body by invoking the json function on the Response object. JavaScript изменяет страницу, используя сведения из ответа API. JavaScript updates the page with the details from the web API’s response.

Самый простой вызов fetch принимает один параметр, представляющий маршрут. The simplest fetch call accepts a single parameter representing the route. Второй параметр (объект init ) является необязательным. A second parameter, known as the init object, is optional. init используется для настройки запроса HTTP. init is used to configure the HTTP request.

Настройте в приложении обслуживание статических файлов и включите сопоставление файлов по умолчанию. Configure the app to serve static files and enable default file mapping. Вставьте в метод Configure в файле Startup.cs следующий выделенный код: The following highlighted code is needed in the Configure method of Startup.cs:

Создайте папку wwwroot в корневом каталоге проекта. Create a wwwroot folder in the project root.

Создайте папку js в папке wwwroot. Create a js folder inside of the wwwroot folder.

Добавьте HTML-файл index.html в папку wwwroot. Add an HTML file named index.html to the wwwroot folder. Замените содержимое файла index.html следующей разметкой: Replace the contents of index.html with the following markup:

Добавьте CSS-файл с именем site.css в папку wwwroot/css. Add a CSS file named site.css to the wwwroot/css folder. Замените содержимое файла site.css следующими стилями: Replace the contents of site.css with the following styles:

Добавьте файл JavaScript с именем site.js в папку wwwroot/js. Add a JavaScript file named site.js to the wwwroot/js folder. Замените содержимое файла site.js следующим кодом: Replace the contents of site.js with the following code:

Может потребоваться изменение параметров запуска проекта ASP.NET Core для локального тестирования HTML-страницы: A change to the ASP.NET Core project’s launch settings may be required to test the HTML page locally:

1. Откройте файл Properties\launchSettings.json. Open Properties\launchSettings.json.
2. Удалите свойство launchUrl , чтобы приложение открылось через index.html — файл проекта по умолчанию. Remove the launchUrl property to force the app to open at index.html—the project’s default file.

В этом примере вызываются все методы CRUD в веб-API. This sample calls all of the CRUD methods of the web API. Ниже приводится пояснение запросов веб-API. Following are explanations of the web API requests.

Получение списка элементов задач Get a list of to-do items

В следующем коде HTTP-запрос GET направляется по пути api/TodoItems: In the following code, an HTTP GET request is sent to the api/TodoItems route:

Когда веб-API возвращает код состояния, указывающий на успешное выполнение, вызывается функция _displayItems . When the web API returns a successful status code, the _displayItems function is invoked. Каждый элемент списка задач в параметре массива, который принимается _displayItems , добавляется в таблицу с помощью кнопок Изменить и Удалить. Each to-do item in the array parameter accepted by _displayItems is added to a table with Edit and Delete buttons. Если запрос веб-API завершается сбоем, в консоли браузера регистрируется сообщение об ошибке. If the web API request fails, an error is logged to the browser’s console.

Добавление элемента задачи Add a to-do item

В приведенном ниже коде выполняется следующее: In the following code:

• Переменная item объявляется для создания представления объектного литерала элемента списка задач. An item variable is declared to construct an object literal representation of the to-do item.
• Для запроса Fetch настраиваются следующие параметры: A Fetch request is configured with the following options:
  • method определяет команду действия HTTP POST. method —specifies the POST HTTP action verb.
  • body определяет представление JSON текста запроса. body —specifies the JSON representation of the request body. JSON создается путем передачи литерала объекта, хранящегося в item , в функцию JSON.stringify. The JSON is produced by passing the object literal stored in item to the JSON.stringify function.
  • headers определяет заголовки Accept и Content-Type запросов HTTP. headers —specifies the Accept and Content-Type HTTP request headers. Для обеих параметров устанавливается значение application/json , чтобы классифицировать тип носителя при получении и отправке соответственно. Both headers are set to application/json to specify the media type being received and sent, respectively.
• HTTP-запрос POST направляется по пути api/TodoItems. An HTTP POST request is sent to the api/TodoItems route.

Когда веб-API возвращает код состояния, указывающий на успешное выполнение, вызывается функция getItems для обновления таблицы HTML. When the web API returns a successful status code, the getItems function is invoked to update the HTML table. Если запрос веб-API завершается сбоем, в консоли браузера регистрируется сообщение об ошибке. If the web API request fails, an error is logged to the browser’s console.

Обновление элемента задачи Update a to-do item

Обновление элемента списка задач аналогично его добавлению. Но есть два существенных отличия: Updating a to-do item is similar to adding one; however, there are two significant differences:

• Путь имеет суффикс с уникальным идентификатором обновляемого элемента. The route is suffixed with the unique identifier of the item to update. Например, api/TodoItems/1. For example, api/TodoItems/1.
• Команда действия HTTP — это PUT, как указано в параметре method . The HTTP action verb is PUT, as indicated by the method option.

Удаление элемента задачи Delete a to-do item

Чтобы удалить элемент списка задач, укажите для параметра запроса method значение DELETE и определите уникальный идентификатор элемента в URL-адресе. To delete a to-do item, set the request’s method option to DELETE and specify the item’s unique identifier in the URL.

Перейдите к следующему руководству, в котором описано, как создавать страницы справки по веб-API: Advance to the next tutorial to learn how to generate web API help pages:

Национальная библиотека им. Н. Э. Баумана
Bauman National Library

Персональные инструменты

JavaScript API

JavaScript API (сокращенно JS API) — набор программных интерфейсов для создания приложений. Библиотека позволяет осуществлять вызовы API прямо из браузера пользователя, минуя сервер, помогая при этом экономить трафик и вычислительные ресурсы. Кроме того, она дает доступ к некоторым возможностям, которые не доступны для вызова с сервера. Широко используется такими компаниями, как Yandex и Mai.ru, где JS API предоставляет возможность разрабатывать приложения в Моем Мире и подключать внешние сайты с использованием JavaScript. JavaScript API поддерживает обратную совместимость, написанный один раз код будет корректно работать с выходом новых версий. Функции JavaScript API можно расширить за счёт модулей — готовых решений других разработчиков.

Содержание

Требования к скрипту

• скрипт будет встраиваться в страницы сторонних веб-приложений;
• скрипт должен выполнять свою работу качественно;
• скрипт должен загружаться быстро;
• скрипт не должен (непредсказуемо) влиять на работу веб-приложения;
• скрипт должен соответствовать требованиям безопасности.

5 принципов написания встраиваемых скриптов

1. Система сборки
Сборка необходима, потому что:

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

Собирать нужно конкатенацией (операция склеивания объектов линейной структуры), потому что основной скрипт должен загружаться быстро, то есть одним файлом. В связи с этим, нужно всё собрать в один файл. Необязательные, дополнительные возможности нужно подгружать лишь тогда, когда клиент библиотеки вызывает соответствующие методы. Но ядро должно загрузиться быстро, хорошо закэшироваться и сразу предоставить клиенту API. Весь скрипт при этом надо завернуть в один scope, чтобы обернуть код в scope с помощью Grunt, используйте options banner и footer.
Это будет выглядеть таким образом:

2. Переключение между локальной и продакшн конфигурацией
Чтобы можно было легко управлять сборками и конфигурациями, нужно добавить одну переменную config, положить её в отдельный файл configDev.js или configProd.js и иметь отдельные сборки скрипта. При конкатенации нужно указать, из каких файлов собрать скрипт, — и цельный файл-скрипт готов.
Пример prod config-файла:

3. Как передать API наружу?

При помощи кода :

• Тестировать несколько версий библиотеки на странице, причём так, что они друг другу не мешают.
• Весь скрипт поместить в один закрытый scope.
• Иметь полный контроль над всеми экземплярами.

4. “Правильная” система модулей При конкатенации кода таких модулей всё будет работать безо всяких библиотек для модулей.

5. Инициализация API
Если в библиотеке есть хоть какая-то инициализация, то нужно вынести её в отдельный метод. Можно даже создать отдельный метод для инициализации в каждом модуле. [Источник 1] Общая структура кода может выглядеть таким образом:

Примеры JavaScript API

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

Этот API доступен через свойство alarms объекта window.navigator. Объект alarms предоставляет три метода:

1. getAll(): возвращает список всех уведомлений на данном устройстве в виде массива объектов Alarm.
2. add(): регистрирует новое уведомление по указанной дате и возвращает объект типа AlarmRequest.
3. remove(): удаляет ранее добавленное уведомление по его уникальному идентификатору (уникальному в границах приложения).

• Presentation API предоставляет веб-приложениям доступ к дополнительным устройствам отображения, таким как проектор или подключенный телевизор. Этот API работает как с проводными (HDMI, DVI и др.) так и беспроводными (MiraCast, Chromecast, DLNA, AirPlay) технологиями. Все что делает этот API, это позволяет обмениваться сообщениями между скриптами на вашей странице и на странице презентации на дополнительном дисплее.

Данный API доступен по свойству presentation объекта window.navigator object. Данное свойство предоставляет метод requestSession() и два события present и availablechange. Метод requestSession() используется для запуска и восстановления сеанса презентации на дополнительном экране. Он возвращает объект сессии презентации. Когда содержимое по url адресу переданному в метод requestSession() загружается, страница на экране презентации получает событие present. Когда подсоединяется первый или отключается последний дополнительный монитор, происходит событие availablechange.

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

Standby API доступен через свойство wakeLock объекта window.navigator. Это свойство предоставляет два метода:

1. request: заставляет устройство не отключать экран.
2. release: разрешает устройству отключать экран по своему усмотрению.

Оба метода принимают только один аргумент, строку «screen» или «system». Первый вариант используется чтобы указать, что нужно не отключать экран, второй для того, чтобы указать на другие устройства, например процессор или радио (но не экран). [Источник 2]

Подключение JavaScript API

Возможно IFrame-приложении или на внешнем сайте.

Подключение на внешнем сайте

Для использования JS API необходимо:

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

• Загрузить библиотеку с помощью вызова функции mailru.loader.require(part, callback). Первым аргументом в нее передается часть библиотеки, которую надо загрузить (сейчас это только api). Второй аргумент — это функция, которая будет вызвана когда библиотека будет подгружена, выполняйте всю работу с API внутри этой функции.
• Инициализировать библиотеку

1. для приложений: вызвав функцию mailru.app.init(private_key)
2. для сайтов: вызвав функцию mailru.connect.init(app_id, private_key)

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

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

Во Flash-приложении

Возможно использовать все функции JS API внутри Flash части вашего приложения. Для этого у Mail.ru создан Flash API — ActionScript прослойка для вызова функций JS API.

Подключение и работа в Yandex API

Работа с JavaScript API выглядит следующим образом: