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

Статья
04/20/2023

Новые возможности

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

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

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

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

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

Географический регион	Базовый URL-адрес (географическая конечная точка)	Центры обработки данных
Глобальный (`non-regional`)	api.cognitive.microsofttranslator.com	Ближайший доступный центр обработки данных
Азиатско-Тихоокеанский регион	api-apc.cognitive.microsofttranslator.com	Республика Корея, южный регион, Восточная Япония, Юго-Восточная Азия и Восточная Австралия
Европа	api-eur.cognitive.microsofttranslator.com	Северная Европа, Западная Европа
США	api-nam.cognitive.microsofttranslator.com	Восточная часть США, центрально-южная часть США, центрально-западная часть США и западная часть США 2

¹ Клиенты с ресурсом, расположенным в Северной Швейцарии или Западной Швейцарии, могут гарантировать, что их запросы API текста обслуживаются в Швейцарии. Чтобы гарантировать обработку запросов в Швейцарии, создайте ресурс Переводчика в регионе ресурсов "Северная Швейцария" или "Западная Швейцария", а затем используйте пользовательскую конечную точку ресурса в запросах API. Например, если вы создаете ресурс Переводчика в портал Azure с параметром "Регион ресурса" в качестве "Северная Швейцария" и имя ресурса 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

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

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

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

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

Заголовки	Описание
Ocp-Apim-Subscription-Key	Используйте с подпиской Cognitive Services, если вы передаете секретный ключ. Значение — это секретный ключ Azure для вашей подписки на Переводчик.
Авторизация	Используйте с подпиской Cognitive Services, если вы передаете маркер проверки подлинности. Значением является токен носителя: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Используйте вместе с несколькими службами Cognitive Services и региональным ресурсом переводчика. Значение — это регион нескольких служб или регионального ресурса переводчика. Это значение является необязательным при использовании глобального ресурса переводчика.

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

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

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

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

Заголовки	Описание
Ocp-Apim-Subscription-Key	Значение — это секретный ключ Azure для вашей подписки на Переводчик.

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

// 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?'}]"

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

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

Заголовки	Описание
Ocp-Apim-Subscription-Key	Значение — это секретный ключ Azure для вашей подписки на Переводчик.
Ocp-Apim-Subscription-Region	Значение — это регион ресурса переводчика.

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

// 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?'}]"

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

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

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

Заголовки	Описание
Ocp-Apim-Subscription-Key	Значение — это секретный ключ Azure для вашего ресурса с несколькими службами.
Ocp-Apim-Subscription-Region	Значение — это регион ресурса с несколькими службами.

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

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

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

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

Тип ресурса	Служба проверки подлинности URL-адреса
Глобальный	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Региональный или с несколькими службами	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

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

// 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 минут).

Проверка подлинности с помощью Azure Active Directory (Azure AD)

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

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

Краткое описание: проверка подлинности с помощью Azure Active Directory.
Краткое представление: авторизация доступа к управляемым удостоверениям.

Заголовки

Заголовок	Значение
Авторизация	Значение представляет собой маркер носителя для доступа, созданный Azure AD. Маркер носителя обеспечивает подтверждение проверки подлинности и проверяет авторизацию клиента для использования ресурса. Маркер проверки подлинности действителен в течение 10 минут и должен использоваться повторно при нескольких вызовах Переводчика. См. пример запроса: 2. Получение маркера
Ocp-Apim-Subscription-Region	Значением является регион ресурса переводчика. Для глобального ресурса указывать это значение необязательно.
Ocp-Apim-ResourceId	Значением является идентификатор ресурса для экземпляра ресурса Переводчика. Идентификатор ресурса можно найти в портал Azure в разделе Свойства → ресурсов Переводчика. Формат идентификатора ресурса: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

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

Снимок экрана: страница свойств Переводчика в портал 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 Cognitive Services.

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

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

Перейдите к ресурсу Переводчика в портал Azure.
Выберите Сеть в разделе Управление ресурсами .
На вкладке Брандмауэры и виртуальные сети выберите Выбранные сети и частные конечные точки.
Выберите Сохранить, чтобы применить изменения.
Выберите Ключи и конечная точка в разделе Управление ресурсами .
Перейдите на вкладку виртуальная сеть.
В списке перечислены конечные точки для перевода текста и перевода документов.

Заголовки	Описание
Ocp-Apim-Subscription-Key	Значение — это секретный ключ Azure для вашей подписки на Переводчик.
Ocp-Apim-Subscription-Region	Значение — это регион ресурса переводчика. Это значение является необязательным, если ресурс — `global`

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

// 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 цифры определяют категорию ошибки. Коды распространенных ошибок:

Код	Описание
400000	Недопустимые входные данные в запросе.
400001	Недопустимый параметр "scope" (область).
400002	Недопустимый параметр "category" (категория).
400003	Спецификатор языка отсутствует или является недопустимым.
400004	Спецификатор целевого сценария ("To script") отсутствует или является недопустимым.
400005	Входной текст отсутствует или является недопустимым.
400006	Недопустимая комбинация языка и сценария.
400018	Спецификатор исходного сценария ("From script") отсутствует или является недопустимым.
400019	Один из заданных языков не поддерживается.
400020	Недопустимый элемент в массиве входного текста.
400021	Параметр версии API отсутствует или недопустим.
400023	Одна из заданный пар языков является недопустимой.
400035	Недопустимый исходный язык (поле "From").
400036	Целевой язык (поле "To") отсутствует или является недопустимым.
400042	Недопустимый заданный параметр (поле "Options").
400043	Идентификатор трассировки клиента (поле ClientTraceId или заголовок X-ClientTranceId) отсутствует или является недопустимым.
400050	Входной текст является слишком длинным. Просмотрите ограничения для запросов.
400064	Параметр "translation" (перевод) отсутствует или недопустим.
400070	Количество целевых сценариев (параметр "ToScript") не соответствует количеству целевых языков (параметр "To").
400071	Недопустимое значение для TextType.
400072	В массиве входного текста слишком много элементов.
400073	Недопустимый параметр сценария.
400074	Текст запроса не соответствует формату JSON.
400075	Недопустимое сочетание категории и пары языков.
400077	Превышен максимальный размер запроса. Просмотрите ограничения для запросов.
400079	Система, запрошенная для перевода между данными исходным и целевым языками, не существует.
400080	Транслитерация не поддерживается для этого языка или скрипта.
401000	Запрос не авторизован, так как учетные данные отсутствуют или являются недопустимыми.
401015	"Указаны учетные данные для API распознавания речи. Этот запрос требует учетные данные для API текста. Используйте подписку на Переводчик".
403000	Операция запрещена.
403001	Операция запрещена, так как для подписки превышена бесплатная квота.
405000	Метод запроса не поддерживается для запрашиваемого ресурса.
408001	Выполняется подготовка запрошенной системы перевода. Повторите попытку через несколько минут.
408002	Истекло время ожидания входящего потока для запроса. Клиент не создал запрос за время, в течение которого сервер был готов ждать. Клиент может повторить запрос без внесения изменений в любой другой момент.
415000	Заголовок Content-Type отсутствует или является недопустимым.
429000, 429001, 429002	Сервер отклонил запрос, так как клиент превысил ограничения для запросов.
500000	Произошла непредвиденная ошибка. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время ошибки, идентификатор запроса из заголовка ответа X-RequestId и идентификатор клиента из заголовка запроса X-ClientTraceId.
503000	Служба временно недоступна. Повторная попытка. Если ошибка сохраняется, передайте отчет о ней, включив следующие данные: дата и время ошибки, идентификатор запроса из заголовка ответа X-RequestId и идентификатор клиента из заголовка запроса X-ClientTraceId.

Метрики

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

Метрики Переводчика

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

metrics	Описание
TotalCalls	Общее число вызовов API.
TotalTokenCalls	Общее число вызовов API через службу токенов с использованием маркера проверки подлинности.
SuccessfulCalls	Число успешных вызовов.
TotalErrors	Число вызовов с сообщением об ошибке.
BlockedCalls	Число вызовов, превысивших ограничение скорости или квоты.
ServerErrors	Число вызовов с внутренней ошибкой сервера (5XX).
ClientErrors	Число вызовов, приведших к ошибке на стороне клиента (4XX).
Задержка	Длительность выполнения запроса в миллисекундах.
CharactersTranslated	Общее количество символов во входящем текстовом запросе.