Отправка API-запроса через Postman
Рассмотрим, как отправлять HTTP-запросы к модели с помощью Postman.
- Скачайте и установите Postman. Если приложение уже установлено на вашем компьютере, переходите к шагу 2.
- В интерфейсе Postman откройте вкладку Import . В открывшемся диалоговом окне выберите опцию Raw text . В поле ниже вставьте следующий текст.
curl --location --request POST 'https://api.ai.cloud.ru/public/v2/service_auth' \ --header 'Content-Type: application/json' \ --data-raw ' "client_id": "user-xxxxx", "client_secret": "xxxxx" >'
Где client_id , client_secret — это Long API Keys, которые находятся в параметрах разработчика . В интерфейсе программы это выглядит так: 
Для отправки запроса к модели на сервис необходимо указать x-api-key , access_token и x-workspace-id в соответствующих полях. Обратите внимание на то, что x-api-key — это клиентский ключ доступа к API. Он индивидуален для каждого аккаунта пользователя. Его можно узнать несколькими способами:
- Выполните в терминале Jupyter Notebook команду set для вывода всех переменных окружения пользователя. Используйте значение переменной GWAPI_KEY .
- Перейдите в параметры разработчика .
- Выполните в терминале Jupyter Notebook следующий блок:
import os print(os.environ['GWAPI_KEY'])
x-workspace-id — это идентификатор воркспейса. Он индивидуален для каждого воркспейса, созданного пользователем. Способ получения идентификатора приведен в разделе инструкций .
Нажмите Code на правой панели диалога для генерации кода запроса.
Итоговый запрос может выглядеть следующим образом:
curl --location --request POST 'https://api.ai.cloud.ru/public/v2/inference/v1/predict/ / /' \ --header 'X-Api-Key: ' \ --header 'authorization: ' \ --header 'x-workspace-id: \ --header 'Content-Type: application/json' \ --data-raw ' "instances": [ "text": "Hello world!" > ] >'
В ответ на запрос придет результат выполнения метода predict .
Отправить синхронный HTTP-запрос к развернутой модели
После развертывания образа с моделью можно отправлять запросы на хост.
В этой инструкции рассмотрены синхронные запросы, которые позволяют последовательно обрабатывать запросы к модели. Они применяются, если требуется получить ответ для одиночного запроса, который обрабатывается меньше минуты.
Структура запроса
REST API сервиса использует протокол HTTP для отправки данных и ответы в формате JSON. HTTP-запросы можно отправить из консоли с помощью инструмента командной строки curl.
Для проверки корректности запросов с клиента на сервис и получения ответа от бэкенда рекомендуется использовать набор инструментов Postman.
Стандартный HTTP-запрос состоит из следующих частей:
- Конечная точка. URL, который клиент использует для связи с сервисом.
- Метод HTTP. Сообщает сервису, какое действие хочет выполнить клиент.
- Заголовок (header). Используется для передачи дополнительной информации между сервисом и клиентом.
- Тело. Данные, которые отправляются на сервис.
Отправить синхронный запрос, используя ключ
Ключи для получения предсказаний от развернутого деплоя позволяют отправлять запросы к нему, минуя этап аутентификации.
Для отправки запроса к деплою по ключу:
- В главном меню платформы перейдите в Deployments → Деплои .
- Перейдите в карточку нужного деплоя.
- Во вкладке Управление ключами нажмите Сгенерировать ключ .
Созданный ключ является уникальным. - (Опционально) Задайте описание ключа, нажав на плюс в столбце Описание .
- Во вкладке Тест API нажмите cURL , чтобы скопировать запрос.
Запрос будет иметь следующий вид:
Пример скопированного запроса
curl 'https://mlspace.aicloud.sbercloud.ru/deployments/dgx2-inf/kfserving-1629374788/v1/models/kfserving-1629374788:predict' \ -H 'content-type: application/json' \ -H 'x-workspace-id: ee8cd85f-1886-4bbe-a2db-12ce69206a26' \ --data-raw ''
Пример Python-запроса
import requests BASE_URL = "https://mlspace.aicloud.sbercloud.ru/deployments/dgx2-inf/kfserving-1629374788/v1/models/kfserving-1629374788:predict" results = requests.post( BASE_URL, json="key": "value">, headers= "x-workspace-id": "ee8cd85f-1886-4bbe-a2db-12ce69206a26", "content-type":"application/json", "x-api-key":"116708e901aa481a9c9d4200357ed31d" > )
Удалить ключ
Для удаления ключа:
- В главном меню платформы перейдите в Deployments → Деплои .
- Перейдите в карточку нужного деплоя.
- Во вкладке Управление ключами выберите ключ, который необходимо удалить, отметив чекбокс.
- Нажмите на иконку в соответствующей строке списка.
- В появившемся диалоговом окне подтвердите действие.
- Начало работы с API
- Отправка API-запроса через Postman
Как сделать http запрос с api key
Если в Kaspersky Scan Engine включена авторизация HTTP-клиентов, все HTTP-запросы должны содержать токен API.
В следующем примере показан HTTP-запрос, содержащий токен API в поле Authorization :
POST /scanfile HTTP/1.0
* Full path to the EICAR test file *
В этом примере Authorization – это имя по умолчанию для поля заголовка запроса, используемого для авторизации. Вы можете изменить это имя в разделе Authorization Kaspersky Scan Engine GUI.
Ниже приведен пример ответа на запрос:
Date: Mon, 10 February 2014 12:25:21 GMT
Если авторизация не удалась и был указан префикс Bearer, ответ будет следующим:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm=»API Kaspersky Scan Engine»
Если авторизация не удалась и префикс Bearer не был указан, ответ будет следующим:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token realm=»API Kaspersky Scan Engine»
Спецификация выдачи REST API службы запросов
Проверенные учетные данные Microsoft Entra включают REST API службы запросов. Этот API позволяет выдавать и проверять учетные данные. В данной статье описывается, как указать REST API службы запросов для запроса на выдачу. В другой статье описывается, как вызвать REST API службы запросов.
HTTP-запрос
Запрос на выдачу REST API службы запросов поддерживает следующий метод HTTP:
| Способ | Примечания. |
|---|---|
| POST | С полезными данными JSON, как указано в этой статье. |
Запрос на выдачу REST API службы запросов поддерживает следующие заголовки HTTP:
| Имя. | Значение |
|---|---|
| Authorization | Вложите маркер доступа в качестве маркера носителя в заголовок авторизации в HTTP-запросе. Например, Authorization: Bearer . |
| Content-Type | application/json |
Создайте HTTP-запрос POST к REST API службы запросов.
https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest Приведенный ниже HTTP-запрос демонстрирует запрос к REST API службы запросов:
POST https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest Content-Type: application/json Authorization: Bearer < "includeQRCode": true, "callback": < "url": "https://contoso.com/api/issuer/issuanceCallback", "state": "Aaaabbbb11112222", "headers": < "api-key": "an-api-key-can-go-here" >>, . > Для вызова REST API службы запросов требуется приведенное разрешение. Дополнительные сведения см. в статье Настройка арендатора для использования службы проверяемых удостоверений Azure AD (предварительная версия).
| Тип разрешения | Разрешение |
|---|---|
| Приложение | 3db474b9-6a0c-4840-96ac-1fceb342124f/.default |
Полезные данные запроса на выдачу
Полезные данные запроса на выдачу содержат сведения о запросе на выдачу проверяемого удостоверения. В следующем примере демонстрируется запрос на выдачу с использованием потока PIN-кода с пользовательскими утверждениями, такими как имя и фамилия. Результатом этого запроса является QR-код со ссылкой для запуска процесса выдачи.
< "includeQRCode": false, "callback": < "url": "https://contoso.com/api/issuer/issuanceCallback", "state": "de19cb6b-36c1-45fe-9409-909a51292a9c", "headers": < "api-key": "OPTIONAL API-KEY for CALLBACK EVENTS" >>, "authority": "did:web:verifiedid.contoso.com", "registration": < "clientName": "Verifiable Credential Expert Sample" >, "type": "VerifiedCredentialExpert", "manifest": "https://verifiedid.did.msidentity.com/v1.0/tenants/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/MTIzNDU2NzgtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwdmVyaWZpZWRjcmVkZW50aWFsZXhwZXJ0/manifest", "pin": < "value": "3539", "length": 4 >, "claims": < "given_name": "Megan", "family_name": "Bowen" >, "expirationDate": "2024-12-31T23:59:59.000Z" > Полезная нагрузка содержит следующие свойства:
| Параметр | Тип | Описание |
|---|---|---|
| includeQRCode | Логический | Определяет, включается ли QR-код в ответ на этот запрос. Представьте QR-код и попросите пользователя просканировать его. После сканирования QR-кода запускается приложение проверки подлинности с данным запросом на выдачу. Возможные значения: true (по умолчанию) или false . Если задано значение false , используйте возвращаемое свойство url для отображения прямой ссылки. |
| callback | Callback | Обязательно. Позволяет разработчику асинхронно получать информацию о потоке во время процесса выдачи проверяемого удостоверения. Например, разработчику может потребоваться выполнять вызов после того, как пользователь просканировал QR-код, или в случае успешного выполнения или сбоя запроса на выдачу. |
| authority | строка | Децентрализованный идентификатор издателя (DID). Дополнительные сведения см. в разделе Получение сведений об удостоверении и среде для настройки приложения. |
| registration | RequestRegistration | Предоставляет сведения об издателе, которые могут быть отображены в приложении проверки подлинности. |
| type | строка | тип проверяемого удостоверения; Должен соответствовать типу, определенному в манифесте проверяемого удостоверения. Например: VerifiedCredentialExpert . Дополнительные сведения см. в разделе Создание карточки эксперта с проверенным удостоверением в Azure. |
| manifest | строка | URL-адрес документа манифеста проверяемого удостоверения. Дополнительные сведения см. в разделе Получение сведений об удостоверении и среде для настройки приложения. |
| claims | строка | Необязательно. Можно использовать только для потока аттестации маркеров идентификатора, чтобы включить коллекцию утверждений, сделанных о субъекте в проверяемые учетные данные. |
| pin | КОНТАКТНЫЙ | Необязательно. Пин-код можно использовать только с потоком аттестации маркеров идентификатора. PIN-код для обеспечения дополнительной защиты во время выдачи. Вы создаете PIN-код и предоставляете его пользователю в своем приложении. Пользователь должен предоставить созданный вами PIN-код. |
| expirationDate | строка | Необязательно. Срок действия срока действия можно использовать только с потоком аттестации маркеров идентификатора. Если задано, значение должно быть датой, выраженной в формате ISO8601 . Дата переопределит допустимостьInterval в определении правил учетных данных для этого запроса на выдачу. Используйте этот параметр для явного управления сроком действия учетных данных, например окончания дня, окончания или конца года, независимо от того, когда он будет выдан. Обратите внимание, что дата выражена в формате UTC. Если указать конец года, если задано 23:59:59 значение времени , то есть 1 секунда до полуночи в формате UTC. Любой пользователь в другом часовом поясе получит дату окончания срока действия, представленную в локальном часовом поясе в Microsoft Authenticator. Это означает, что если вы находитесь в часовом поясе CET, оно будет представлено как 1 января 1 утра. |
В настоящее время существует четыре типа аттестации утверждений, которые можно отправить в полезных данных. Проверенный идентификатор Microsoft Entra использует четыре способа вставки утверждений в проверяемые удостоверения и подтверждения этой информации с помощью DID издателя. Ниже перечислены эти четыре типа:
- Маркер идентификации
- Указание для маркера идентификации
- Проверяемые удостоверения посредством проверяемой презентации.
- Самопроверяемые утверждения
Подробные сведения о типах входных данных см. в статье Настройка проверяемых учетных данных.
Тип RequestRegistration
Тип RequestRegistration обеспечивает регистрацию сведений для издателя. Тип RequestRegistration содержит перечисленные ниже свойства.
| Свойство | Type | Описание: |
|---|---|---|
| clientName | строка | Отображаемое имя издателя проверяемого удостоверения. |
| logoUrl | строка | Необязательно. URL-адрес логотипа издателя. |
| termsOfServiceUrl | строка | Необязательно. URL-адрес условий использования проверяемого удостоверения, которое вы выдаете. |
В настоящее время сведения RequestRegistration не отображаются во время выдачи в приложении Microsoft Authenticator. Однако эти сведения можно использовать в полезных данных.
Тип обратного вызова
REST API службы запросов создает несколько событий для конечной точки обратного вызова. Эти события позволяют обновить пользовательский интерфейс и продолжить процесс после возврата результатов в приложение. Тип Callback содержит перечисленные ниже свойства.
| Свойство | Type | Описание: |
|---|---|---|
| url | строка | Универсальный код ресурса (URI) конечной точки обратного вызова приложения. Универсальный код ресурса (URI) должен указывать на достижимую конечную точку в Интернете. В противном случае служба выдаст ошибку о невозможности прочитать URL-адрес обратного вызова. Допустимые форматы: IPv4, IPv6 или разрешаемое DNS-имя узла. |
| state | строка | Сопоставляет событие обратного вызова со статусом, переданным в исходных полезных данных. |
| headers | строка | Необязательно. Можно включить коллекцию заголовков HTTP, требуемых стороной, принимающей сообщение POST. Текущие поддерживаемые значения заголовка — заголовки api-key или Authorization . Любой другой заголовок приведет к ошибке недопустимого заголовка обратного вызова |
Тип pin
Тип pin определяет PIN-код, который может отображаться при выдаче. pin является необязательным и, если используется, всегда должен отправляться по внешнему каналу. При использовании PIN-кода на основе хэша необходимо определить свойства salt , alg и iterations . pin содержит следующие свойства:
| Свойство | Type | Описание: |
|---|---|---|
| value | строка | Содержит значение PIN-кода в виде обычного текста. Если вы используете хэшированный PIN-код, то свойство value содержит случайный хэш в формате Base64. |
| type | строка | Тип PIN-кода. Возможное значение: numeric (по умолчанию). |
| length | integer | Длина PIN-кода. Длина по умолчанию равна 6, минимальная длина — 4, а максимальная — 16. |
| salt | строка | Соль хэшированного PIN-кода. Соль добавляется в начало кода при вычислении хэша. Кодировка: UTF-8. |
| alg | строка | Алгоритм хэширования для хэшированного PIN-кода. Поддерживаемый алгоритм: sha256 . |
| iterations | integer | Число итераций хэширования. Возможное значение: 1 . |
Успешный ответ
В случае успешного выполнения этот метод возвращает код ответа (HTTP 201 Created) и коллекцию объектов event в тексте ответа. В следующем примере JSON показан успешный ответ:
Результат содержит следующие свойства.
| Свойство | Type | Описание: |
|---|---|---|
| requestId | строка | Автоматически сформированный идентификатор запроса. Обратный вызов использует тот же запрос, что позволяет отслеживать запрос на выдачу и его обратные вызовы. |
| url | строка | URL-адрес, который запускает приложение проверки подлинности и запускает процесс выдачи. Вы можете предоставить этот URL-адрес пользователю, если он не может просканировать QR-код. |
| expiry | integer | Указывает, когда истечет срок действия ответа. |
| qrCode | строка | QR-код, который пользователь может просканировать для запуска потока выдачи. |
Когда ваше приложение получает ответ, оно должно предоставить пользователю QR-код. Пользователь сканирует QR-код, который открывает приложение проверки подлинности и запускает процесс выдачи.
Отклик в случае ошибки
При возникновении ошибки с запросом возвращается ответ на ошибку и должен обрабатываться соответствующим образом приложением.
События обратного вызова
Конечная точка обратного вызова вызывается, когда пользователь сканирует QR-код, использует прямую ссылку на приложение проверки подлинности или завершает процесс выдачи.
- request_retrieved : пользователь просканировал QR-код или выбрал ссылку, которая запускает поток выдачи.
- issuance_successful : выдача проверяемого удостоверения выполнена успешно.
- issuance_error : при выдаче произошла ошибка. Дополнительные сведения см. в свойстве error .
В следующем примере показаны полезные данные обратного вызова, когда приложение проверки подлинности запускает запрос на выдачу:
В следующем примере показаны полезные данные обратного вызова после того, как пользователь успешно завершает процесс выдачи:
Ошибки обратного вызова
При вызове конечной точки обратного вызова может быть получено сообщение об ошибке. В следующей таблице перечислены коды ошибок.
| Message | Определение |
|---|---|
| fetch_contract_error | Не удалось получить контракт проверяемого удостоверения. Эта ошибка обычно возникает, когда API не может получить манифест, указанный в объекте RequestIssuance полезных данных запроса. |
| issuance_service_error | Служба проверяемых удостоверений не может проверить требования или обнаружена ошибка в проверяемом удостоверении. |
| unspecified_error | Эта ошибка встречается редко, но ее стоит изучить. |
В следующем примере демонстрируется полезная нагрузка обратного вызова при возникновении ошибки: