Начало работы: REST API сервисы перевода документов

Перевод документов — это облачная функция службы Azure Translator in Foundry Tools , которая асинхронно преобразует целые документы на поддерживаемых языках и различных форматах файлов. В этом кратком руководстве вы узнаете, как использовать перевод документов с выбранным языком программирования для перевода исходного документа на целевой язык при сохранении структуры и форматирования текста.

API перевода документов поддерживает два процесса перевода:

• Асинхронный пакетный перевод поддерживает обработку нескольких документов и больших файлов. Для процесса пакетного перевода требуется учетная запись хранения BLOB-объектов Azure с контейнерами хранения для исходного и переведенного документа.

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

Давайте начнем.

Необходимые компоненты

наличие активной подписки Azure. Если у вас нет подписки Azure, создайте ее бесплатно.

• После получения подписки Azure создайте ресурс Azure Translator на портале Azure.

  Примечание.

  • В этом кратком руководстве мы рекомендуем использовать единый глобальный ресурс Azure Translator, если только для вашего бизнеса или приложения не требуется использование определенного региона. Если вы планируете использовать управляемое удостоверение, назначаемое системой, для проверки подлинности, выберите географический регион, например западная часть США.
  • При использовании глобального ресурса с одним обслуживанием вы включаете один заголовок авторизации (Ocp-Apim-Subscription-key) с запросом REST API. Значением Ocp-Apim-Subscription-key является секретный ключ Azure для подписки Azure Translator Text.

• После развертывания ресурса выберите элемент Перейти к ресурсу, чтобы получить ключ и конечную точку.

  • Для подключения приложения к Azure Translator требуется ключ и конечная точка из ресурса. Вставьте ключ и конечную точку в код далее в кратком руководстве. Эти значения можно найти на странице "Ключи портал Azure" и "Конечная точка".

    

• Для этого проекта мы используем средство командной строки cURL для вызова REST API.

  Примечание.

  Пакет cURL предварительно установлен в большинстве дистрибутивов Windows 10 и Windows 11, а также в большинстве дистрибутивов macOS и Linux. Вы можете проверить версию пакета со следующими командами: Windows: curl.exe -V macOS curl -V Linux: curl --version

Асинхронно перевод документов (POST)

1. С помощью предпочтительного редактора или интегрированной среды разработки создайте новый каталог для вашего приложения с именем document-translation.

2. Создайте файл JSON с именем document-translation.json в каталоге перевода документов.

3. Скопируйте и вставьте пример запроса на перевод документов в document-translation.json файл. Замените и {your-source-container-SAS-URL} замените {your-target-container-SAS-URL} значениями из экземпляра контейнеров учетной записи хранения портал Azure.

   Пример запроса:

   {
     "inputs":[
       {
         "source":{
           "sourceUrl":"{your-source-container-SAS-URL}"
         },
         "targets":[
           {
             "targetUrl":"{your-target-container-SAS-URL}",
             "language":"fr"
           }
         ]
       }
     ]
   }
   

Авторизация контейнера хранилища

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

✔️ Управляемое удостоверение. Управляемое удостоверение — это субъект-служба, создающий удостоверение Microsoft Entra и определенные разрешения для управляемого ресурса Azure. Управляемые удостоверения позволяют запускать приложение Azure Translator без необходимости внедрять учетные данные в код. Управляемые удостоверения — это более безопасный способ предоставления доступа к данным хранилища и замены требования к включению маркеров подписи общего доступа (SAS) с исходными и целевыми URL-адресами.

Дополнительные сведения см. в разделе"Управляемые удостоверения" для перевода документов.

✔️ Подписанный URL-адрес (SAS). Подписанный URL-адрес — это URL-адрес, предоставляющий ограниченный доступ в течение указанного периода времени переводчику. Чтобы использовать этот метод, необходимо создать токены совместного доступа (SAS) для исходного и целевого контейнеров. sourceUrl и targetUrl должны содержать токен общего доступа (SAS), добавленный в качестве строки запроса. Маркер можно назначить контейнеру или определенным BLOB-объектам.

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

Дополнительные сведения см. в разделе"Создание маркеров SAS".

Создание и запуск запроса POST

Перед выполнением запроса POST замените {your-document-translator-endpoint} и {your-key} на значения из экземпляра Azure Translator на портале Azure.

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

командная строка или терминал

curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

После успешного завершения:

• Переведенные документы можно найти в целевом контейнере.
• Успешный метод POST возвращает код ответа, указывающий 202 Accepted , что служба создала пакетный запрос.
• Запрос POST также возвращает заголовки ответа, включая Operation-Location значение, используемое в последующих запросах GET.

Синхронно перевод одного документа (POST)

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

✔️ Дополнительные сведения см. в contentTypeразделе"Поддерживаемые форматы документов".

Сборка и запуск синхронного запроса POST

1. Для этого проекта требуется пример документа. Вы можете скачать наш пример документа Microsoft Word для этого краткого руководства. Исходный язык — английский.

2. Перед выполнением запроса POST замените {your-document-translation-endpoint} и {your-key} на значения из экземпляра Azure Translator на портале Azure.

   Внимание

   Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например Azure Key Vault. Дополнительные сведения см. в разделе"Безопасность средств Foundry".

   командная строка или терминал

   
   curl -i -X POST "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"
   

   PowerShell

   cmd /c curl "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}
   
   

   ✔️ Дополнительные сведения см. в Query parametersразделе синхронного перевода документов.

После успешного завершения:

• Переведенный документ возвращается с ответом.
• Успешный метод POST возвращает код ответа, указывающий 200 OK , что служба создала запрос.

Готово, поздравляем! Вы только что узнали, как переводить документы с помощью Azure Translator.

Следующие шаги