Переводчик версии 3.0

Что нового?

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

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

Базовые URL-адреса

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

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

✔️ Функция: переводчик текста

Конечные точки сервисов Швейцарии

Клиенты с ресурсом, расположенным в Северной Или Западной Швейцарии, могут гарантировать, что запросы API текста обслуживаются в Швейцарии. Чтобы убедиться, что запросы обрабатываются в Швейцарии, создайте ресурс Переводчика в Resource region, Switzerland North или Switzerland West, а затем используйте пользовательскую конечную точку этого ресурса в ваших запросах API.

Например, если вы создаете ресурс Переводчика в портале Azure с именем Resource region как Switzerland North, а имя ресурса — my-swiss-n, то конечная точка https​://my-swiss-n.cognitiveservices.azure.com — это ваша пользовательская конечная точка. Пример запроса для перевода:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

Пользовательский переводчик в настоящее время недоступен в Швейцарии.

Аутентификация

Подпишитесь на Переводчик или мультислужбу в службах ИИ Azure и используйте ключ (доступный на портале Azure) для проверки подлинности.

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

Секретный ключ

Первым вариантом является проверка подлинности с помощью заголовка Ocp-Apim-Subscription-Key . Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> Добавьте заголовок в запрос.

Проверка подлинности с помощью глобального ресурса

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

Ниже приведен пример запроса на вызов переводчика с помощью глобального ресурса переводчика

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Проверка подлинности с помощью регионального ресурса

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

Ниже приведен пример запроса на вызов переводчика с помощью регионального ресурса переводчика

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Проверка подлинности с помощью ресурса с несколькими службами

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

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

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

Если вы передаете секретный ключ в строке запроса с параметром Subscription-Key, необходимо указать регион с параметром Subscription-Regionзапроса.

Проверка подлинности с помощью маркера доступа

Кроме того, вы можете обменять секретный ключ на маркер доступа. Этот маркер включается в каждый запрос в качестве заголовка Authorization . Чтобы получить маркер авторизации, выполните POST запрос по следующему URL-адресу:

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

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Ниже приведены примеры запросов на получение маркера, заданного секретным ключом для регионального ресурса, расположенного в центральной части США:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

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

Authorization: Bearer <Base64-access_token>

Маркер проверки подлинности действителен в течение 10 минут. Маркер следует повторно использовать при выполнении нескольких вызовов переводчика. Однако если программа запрашивает переводчика в течение длительного периода времени, программа должна запрашивать новый маркер доступа через регулярные интервалы (например, каждые 8 минут).

Проверка подлинности с помощью Microsoft Entra ID

Переводчик версии 3.0 поддерживает проверку подлинности Microsoft Entra, облачное решение для управления удостоверениями и доступом Майкрософт. Заголовки авторизации позволяют службе Переводчика проверить, разрешен ли запрашивающий клиент использовать ресурс и завершить запрос.

Необходимые условия

• Краткое представление о том, как пройти проверку подлинности с помощью идентификатора Microsoft Entra.

• Краткое представление о том, как авторизовать доступ к управляемым удостоверениям.

Заголовки

Страница свойств Переводчика — портал Azure

Примеры

Использование глобальной конечной точки

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Использование пользовательской конечной точки

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Примеры использования управляемых удостоверений

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

С глобальной конечной точкой

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

С пользовательской конечной точкой

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Поддержка виртуальной сети

Теперь служба Переводчика доступна с возможностями виртуальной сети (VNET) во всех регионах общедоступного облака Azure. Сведения о включении виртуальной сети см. в статье"Настройка виртуальных сетей служб ИИ Azure".

После включения этой возможности необходимо использовать пользовательскую конечную точку для вызова переводчика. Вы не можете использовать глобальную конечную точку переводчика ("api.cognitive.microsofttranslator.com") и не можете пройти проверку подлинности с помощью маркера доступа.

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

1. Перейдите к ресурсу Переводчика на портале Azure.

2. Выберите "Сеть" в разделе "Управление ресурсами".

3. На вкладке "Брандмауэры и виртуальные сети " выберите выбранные сети и частные конечные точки.

   

4. Нажмите кнопку Сохранить, чтобы применить изменения.

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

6. Перейдите на вкладку "Виртуальная сеть ".

7. Перечислены конечные точки для перевода текста и перевода документов.

   

Ниже приведен пример запроса на вызов переводчика с помощью пользовательской конечной точки

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Ошибки

Стандартный ответ об ошибке — это объект JSON с именем errorи парой "значение". Значение также является объектом JSON со свойствами:

• code: код ошибки, определенный сервером.
• message: строка, предоставляющая удобочитаемое пользователем представление ошибки.

Например, клиент с бесплатной пробной подпиской получит следующую ошибку после исчерпания бесплатной квоты:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

Код ошибки представляет собой число из 6 знаков, первые 3 из которых являются кодом состояния HTTP, а оставшиеся 3 цифры определяют категорию ошибки. Коды распространенных ошибок:

Метрики

Метрики позволяют просматривать сведения об использовании переводчика и доступности на портале Azure. Дополнительные сведения см. в разделе "Метрики данных и платформы".

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