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

2025-02-04

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

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

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

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

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

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

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

Примечание.

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

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

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

Пример запроса:
```
{
  "inputs":[
    {
      "source":{
        "sourceUrl":"{your-source-container-SAS-URL}"
      },
      "targets":[
        {
          "targetUrl":"{your-target-container-SAS-URL}",
          "language":"fr"
        }
      ]
    }
  ]
}
```

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

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

Внимание

Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например Azure Key Vault. Дополнительные сведения см. в статье "Безопасность служб искусственного интеллекта 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, необходимо включить следующие заголовки с каждым запросом. Не беспокойтесь, мы добавим заголовки для вас в пример кода.

Примечание.

Все флаги cURL и параметры командной строки чувствительны к регистру.

Параметр запроса	Description	Условие
`-X` или `--requestPOST`	Флаг -X указывает метод запроса для доступа к API.	Обязательный
`{endpoint}`	URL-адрес конечной точки ресурса перевода документов	Обязательный
`targetLanguage`	Указывает язык выходного документа. Целевой язык должен быть одним из поддерживаемых языков, включенных в область перевода.	Обязательный
`sourceLanguage`	Задает язык входного документа. Если параметр `sourceLanguage` не указан, исходный язык определяется автоматически.	Необязательно
`-H` или `--header"Ocp-Apim-Subscription-Key:{KEY}`	Заголовок запроса, указывающий ключ ресурса перевода документов, разрешающий доступ к API.	Обязательный
`-F` или `--form`	Файловый путь к документу, который требуется включить в запрос. Допускается только один исходный документ.	Обязательный
• `document=` • `type={contentType}/fileExtension`	• Путь к расположению файла для исходного документа. • Тип контента и расширение файла. Ex: "document=@C:\Test\test-file.md; type=text/markdown	Обязательный
`-o` или `--output`	Файловый путь к результатам ответа.	Обязательный
`-F` или `--form`	Файловый путь к необязательному глоссарию для включения в запрос. Для глоссария требуется отдельный `--form` флаг.	Необязательно
• `glossary=` • `type={contentType}/fileExtension`	• Путь к расположению файла для необязательного глоссарийного файла. • Тип контента и расширение файла. Ex: "глоссарий=@C:\Test\glossary-file.txt; type=text/plain	Необязательно

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

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

Для этого проекта требуется пример документа. Вы можете скачать наш пример документа Microsoft Word для этого краткого руководства. Исходный язык — английский.
Перед выполнением запроса POST замените и {your-key} на {your-document-translation-endpoint} значения из экземпляра службы Azure AI Translator портал Azure.

Внимание

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

командная строка или терминал
```
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 AI Translator.

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

Руководство по REST API перевода документов