Учебник. Вызов веб-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:

Введение в web APIs

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

Необходимые знания:	Базовая компьютерная грамотность, понимание основ HTML и CSS, основы JavaScript (см. первые шаги, building blocks, объекты JavaScript).
Цель:	Познакомиться с API, выяснить что они могут делать и как их использовать.

Что такое API?

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

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

Точно также, если мы хотим, например, программировать 3D графику, гораздо легче сделать это с использованием API, написанных на языках высокого уровня, таких как JavaScript или Python.

Note: Смотрите также API в словаре.

API клиентской части JavaScript

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

• API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, API Геолокации (Geolocation API) предоставляет простые в использовании конструкции JavaScript для работы с данными местоположения, так что вы сможете, допустим, отметить своё расположение на карте Google Map. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++) для подключения к устройству GPS (или любому другому устройству геолокации), получения данных и передачи их браузеру для обработки вашей программой, но, как было сказано выше, эти детали скрыты благодаря API.
• Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.

Взаимодействие JavaScript, API и других средств JavaScript

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

• JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node. Но пока не будем останавливаться на этом.
• API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
• Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
• Библиотеки JavaScript — Обычно один или несколько файлов, содержащих пользовательские (custom) функции. Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
• JavaScript фреймворки (frameworks) — Следующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно «писать» веб-приложение с нуля. Главное различие между фреймворками и библиотеками — «Обратное направление управления» ( “Inversion of Control” ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка — наоборот, фреймворк производит вызов кода разработчика.

На что способны API?

Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.

Распространённые API браузера

В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :

• API для работы с документами, загруженными в браузер. Явный пример — DOM (Document Object Model) API, позволяющий работать с HTML и CSS — создавать, удалять и изменять HTML, динамически изменять вид страницы и т.д. Любое всплывающее окно на странице или появляющееся «на ходу» содержимое — всё это благодаря DOM. Узнайте больше об этой категории API на странице Работа с документами.
• API, принимающие данные от сервера, часто используются, чтобы обновить небольшие части веб-страницы. Эта, казалось бы, малая деталь оказывает огромное влияние на производительность и поведение сайтов, так как нет необходимости перезагружать всю страницу целиком, если вам нужно просто обновить список товаров или новых доступных историй. Это также сделает приложение или сайт более отзывчивым и «живым». Список API, благодаря которым это возможно, включает: XMLHttpRequest и Fetch API. Вы также могли встретить термин Ajax, описывающий эту технологию. Узнать больше об этой категории API на странице Получение данных от сервера.
• API для работы с графикой широко поддерживаются браузерами, самые популярные: Canvas и WebGL, позволяющие программно изменять данные о пикселях, содержащиеся в элементе HTML для создания 2D и 3D изображений. Например, вы можете нарисовать фигуры, скажем, прямоугольники или круги, импортировать изображение в canvas и применить к нему фильтры, такие как сепия или оттенки серого с помощью Canvas API, или создать сложное 3D-изображение с освещением и текстурами, используя WebGL. Такие API часто используют в сочетании с API создания анимационных циклов (таких как window.requestAnimationFrame() ) и другими для создания постоянно меняющегося изображения на экране, как в мультфильмах или играх .
• Аудио и Видео API как HTMLMediaElement , Web Audio API, и WebRTC позволяют делать действительно интересные вещи с мультимедиа. Например, создать собственный пользовательский интерфейс (User Interface, UI) для проигрывания аудио/видео, вывод на экран субтитров, записывать видео с веб-камеры для обработки в canvas (см. выше) или для передачи на другой компьютер в видео-конференции, применять звуковые эффекты к аудио-файлам (такие как gain, distortion, panning и т.д.).
• API устройств — в основном, API для обработки и считывания данных с современных устройств удобным для работы веб-приложений образом. Мы уже говорили об API Геолокации, позволяющем считать данные о местоположении устройства. Другие примеры включают уведомление пользователя о появившемся обновлении для веб-приложения с помощью системных уведомлений (см. Notifications API) или вибрации (см. Vibration API).
• API хранения данных на стороне пользователя приобретают всё большее распространение в веб-браузерах — возможность хранить информацию на стороне клиента очень полезна, когда необходимо создать приложение, которое будет сохранять своё состояние между перезагрузками страницы, или даже работать, когда устройство не в сети. В данный момент доступно немало таких API. Например, простое хранилище данных в формате имя/значение (name/value) Web Storage API или хранилище данных в формате таблиц IndexedDB API.

Распространённые сторонние API

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

• Twitter API для добавления такой функциональности, как показ последних твитов на сайте.
• Google Maps API для работы с картами на веб-странице (интересно, что Google Maps также использует этот API). Теперь это целый набор API, который может справляться с широким спектром задач, как свидетельствует Google Maps API Picker.
• Набор Facebook API позволяет использовать различные части платформы Facebook в вашем приложении, предоставляя, например, возможность входа в систему с логином Facebook, оплаты покупок в приложении, демонстрация целевой рекламы и т.д.
• YouTube API, предоставляющий возможность встраивать видео с YouTube на вашем сайте, производить поиск, создавать плейлисты и т.д.
• Twilio API — фреймворк для встраивания функциональности голосовой и видео связи в вашем приложении, отправки SMS/MMS из приложения и т.д.

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

Как работает API?

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

Они основаны на объектах

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

Note: Если вам ещё не известно как работают объекты, советуем вернуться назад и изучить модуль Основы объектов JavaScript прежде чем продолжать.

Вернёмся к примеру с API Геолокации — очень простой API, состоящий из нескольких простых объектов:

• Geolocation , содержит три метода для контроля и получения геоданных.
• Position (en-US) , предоставляет данные о местоположении устройства в заданный момент времени — содержит Coordinates — объект, хранящий координаты и отметку о текущем времени.
• Coordinates , содержит много полезной информации о расположении устройства, включая широту и долготу, высоту, скорость и направление движения и т.д.

Так как же эти объекты взаимодействуют? Если вы посмотрите на наш пример maps-example.html (see it live also), вы увидите следующий код:

Note: Когда вы впервые загрузите приведённый выше пример, появится диалоговое окно, запрашивающее разрешение на передачу данных о местонахождении этому приложению (см. раздел У них есть дополнительные средства безопасности там, где это необходимо далее в этой статье). Вам нужно разрешить передачу данных, чтобы иметь возможность отметить своё местоположение на карте. Если вы всё ещё не видите карту, возможно, требуется установить разрешения вручную; это делается разными способами в зависимости от вашего браузера; например, в Firefox перейдите > Tools > Page Info > Permissions, затем измените настройки Share Location; в Chrome перейдите Settings > Privacy > Show advanced settings > Content settings и измените настройки Location.

Во-первых, мы хотим использовать метод Geolocation.getCurrentPosition() , чтобы получить текущее положение нашего устройства. Доступ к объекту браузера Geolocation производится с помощью свойства Navigator.geolocation , так что мы начнём с

Это эквивалентно следующему коду

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

Метод Geolocation.getCurrentPosition() имеет один обязательный параметр — анонимную функцию, которая запустится, когда текущее положение устройства будет успешно считано. Сама эта функция принимает параметр, являющийся объектом Position (en-US) , представляющим данные о текущем местоположении.

Note: Функция, которая передаётся другой функции в качестве параметра, называется колбэк-функцией (callback function).

Такой подход, при котором функция вызывается только тогда, когда операция была завершена, очень распространён в JavaScript API — убедиться, что операция была завершена прежде, чем пытаться использовать данные, которые она возвращает, в другой операции. Такие операции также называют асинхронными операциями (asynchronous operations). Учитывая, что получение данных геолокации производится из внешнего устройства (GPS-устройства или другого устройства геолокации), мы не можем быть уверены, что операция считывания будет завершена вовремя и мы сможем незамедлительно использовать возвращаемые ею данные. Поэтому такой код не будет работать:

Если первая строка ещё не вернула результат, вторая вызовет ошибку из-за того, что данные геолокации ещё не стали доступны. По этой причине, API, использующие асинхронные операции, разрабатываются с использованием callback function, или более современной системы промисов, которая появилась в ECMAScript 6 и широко используются в новых API.

Мы совмещаем API Геолокации со сторонним API — Google Maps API, который используем для того, чтобы отметить расположение, возвращаемое getCurrentPosition() , на Google Map. Чтобы Google Maps API стал доступен на нашей странице, мы включаем его в HTML документ:

Чтобы использовать этот API, во-первых создадим объект LatLng с помощью конструктора google.maps.LatLng() , принимающим данные геолокации Coordinates.latitude (en-US) и Coordinates.longitude (en-US) :

Этот объект сам является значением свойства center объекта настроек (options), который мы назвали myOptions . Затем мы создаём экземпляр объекта, представляющего нашу карту, вызывая конструктор google.maps.Map() и передавая ему два параметра — ссылку на элемент

Когда это сделано, наша карта отрисовывается.

Последний блок кода демонстрирует два распространённых подхода, которые вы увидите во многих API:

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

Note: Не отчаивайтесь, если вы что-то не поняли из этого примера сразу. Мы рассмотрим использование сторонних API более подробно в следующих статьях.

У них узнаваемые точки входа

При использовании API убедитесь, что вы знаете где точка входа для API. В API Геолокации это довольно просто — это свойство Navigator.geolocation , возвращающее объект браузера Geolocation , внутри которого доступны все полезные методы геолокации.

Найти точку входа Document Object Model (DOM) API ещё проще — при применении этого API используется объект Document , или экземпляр элемента HTML, с которым вы хотите каким-либо образом взаимодействовать, к примеру:

Точки входа других API немного сложнее, часто подразумевается создание особого контекста, в котором будет написан код API. Например, объект контекста Canvas API создаётся получением ссылки на элемент , на котором вы хотите рисовать, а затем необходимо вызвать метод HTMLCanvasElement.getContext() :

Всё, что мы хотим сделать с canvas после этого, достигается вызовом свойств и методов объекта содержимого (content) (который является экземпляром CanvasRenderingContext2D ), например:

Note: вы можете увидеть этот код в действии в нашем bouncing balls demo (see it running live also).

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

Мы уже обсуждали события ранее в этом курсе, в нашей статье Introduction to events — в этой статье детально описываются события на стороне клиента и их применение. Если вы ещё не знакомы с тем, как работают события клиентской части, рекомендуем прочитать эту статью прежде, чем продолжить.

В некоторых API содержится ряд различных событий, в некоторых — событий нет. Свойства обработчика, позволяющие запускать функции при совершении какого-либо события по большей части перечислены в нашем материале отдельного раздела «Обработчики событий (Event handlers)». Как простой пример, экземпляры объекта XMLHttpRequest (каждый представляет собой HTTP-запрос к серверу на получение каких-либо ресурсов (resource)) имеют несколько доступных событий, например, событие load происходит, когда ответ с запрашиваемым ресурсом был успешно возвращён и доступен в данный момент.

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

Note: вы можете увидеть этот код в действии в примере ajax.html (see it live also).

В первых пяти строках мы задаём расположение ресурса, который хотим получить, создаём экземпляр объекта запроса с помощью конструктора XMLHttpRequest() , открываем HTTP-запрос GET , чтобы получить запрашиваемый ресурс, определяем, что мы хотим получить этот ресурс в формате json, после чего отсылаем запрос.

Затем функция-обработчик onload определяет наши действия по обработке ответа сервера. Нам известно, что ответ успешно возвращён и доступен после наступления события load (и если не произойдёт ошибка), так что мы сохраняем ответ, содержащий возвращённый сервером объект JSON в переменной superHeroes , которую затем передаём двум различным функциям для дальнейшей обработки.

У них есть дополнительные средства безопасности там, где это необходимо

Функциональность WebAPI подвержена тем же соображениям безопасности, что и JavaScript или другие веб-технологии (например, same-origin policy), но иногда они содержат дополнительные механизмы защиты. К примеру, некоторые из наиболее современных WebAPI работают только со страницами, обслуживаемыми через HTTPS в связи с передачей конфиденциальных данных (примеры: Service Workers и Push).

К тому же, некоторые WebAPI запрашивают разрешение от пользователя, как только к ним происходит вызов в коде. В качестве примера, вы, возможно, встречали такое диалоговое окно при загрузке нашего примера Geolocation ранее:

Notifications API запрашивает разрешение подобным образом:

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

Итоги

На данном этапе, у вас должно сформироваться представление о том, что такое API, как они работают и как вы можете применить их в своём JavaScript коде. Вам наверняка не терпится начать делать по-настоящему интересные вещи с конкретными API, так вперёд! В следующий раз мы рассмотрим работу с документом с помощью Document Object Model (DOM).