Начало работы с функцией перевода документов

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

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

Примечание

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

  • Перевод документов поддерживается только в плане обслуживания "Стандартный" S1 (с оплатой по мере использования) или в плане оптовых скидок D3. См.Цены на Cognitive Services — Переводчик.

Чтобы приступить к работе, вам потребуется следующее.

  • Активная учетная запись Azure. Если ее нет, можно создать бесплатную учетную запись.

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

  • Ресурс "Переводчик" для одной службы (не является ресурсом Cognitive Services для нескольких служб).

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

    1. Подписка. Выберите одну из доступных подписок Azure.

    2. Группа ресурсов. Можно создать новую группу ресурсов или добавить ресурс в уже существующую группу, которая использует тот же жизненный цикл, разрешения и политики.

    3. Область ресурсов. Выберите Глобальный, если для вашего бизнеса или приложения не требуется конкретный регион. Если вы планируете использовать назначаемое системой управляемое удостоверение для проверки подлинности, выберите неглобальный регион.

    4. Имя. Введите имя, выбранное для ресурса. Выбранное вами имя должно быть уникальным в Azure.

      Примечание

      Для перевода документов требуется конечная точка личного домена. Значение, которое вы введете в поле "Имя", будет параметром имени личного домена для вашей конечной точки.

    5. Ценовая категория. Перевод документов не поддерживается на уровне "Бесплатный". Выберите "Стандартный" S1, чтобы воспользоваться службой.

    6. Выберите Review + Create (Просмотреть и создать).

    7. Проверьте условия обслуживания и щелкните Создать, чтобы развернуть ресурс.

    8. После успешного развертывания ресурса выберите Перейти к ресурсу.

Имя и ключ личного домена

Важно!

  • Конечную точку личного домена необходимо указывать во всех запросах API к службе перевода документов.
  • Вы не сможете использовать ни конечную точку, указанную на портале Azure на странице ресурса Ключи и конечная точка, ни глобальную конечную точку переводчика (api.cognitive.microsofttranslator.com) для создания HTTP-запросов к службе перевода документов.

Что такое конечная точка личного домена?

Конечная точка личного домена — это URL-адрес, отформатированный с учетом имени ресурса, имени узла и подкаталогов переводчика.

https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0

Поиск имени личного домена

Параметр NAME-OF-YOUR-RESOURCE (также называемый пользовательским именем домена) — это значение, введенное в поле Имя при создании ресурса переводчика.

Изображение портала Azure, создание ресурса, мгновенная информация, поле имени.

Получение ключа

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

  1. Если вы создали новый ресурс, после его развертывания выберите Переход к ресурсу. Если у вас есть ресурс перевода документа, перейдите непосредственно на страницу ресурсов.
  2. На левой границе в разделе Управление ресурсами выберите Ключи и конечная точка.
  3. Скопируйте и вставьте ключ в удобное место, например в Блокнот Microsoft.
  4. Вы его вставите в приведенный ниже код, чтобы проверить подлинность запроса к службе перевода документов.

Изображение поля получения ключа на портале Azure.

Создание контейнеров хранилища BLOB-объектов Azure

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

  • Контейнер исходных файлов. В этом контейнере вы отправляете файлы для перевода (обязательно).
  • Контейнер целевых файлов. В этом контейнере будут храниться переведенные файлы (обязательно).

Примечание

Перевод документов поддерживает глоссарии в виде больших двоичных объектов в целевых контейнерах (а не в отдельных контейнерах глоссария). Если требуется включить собственный глоссарий, добавьте его в целевой контейнер и включите glossaryUrl в запрос. Если языковой пары перевода нет в глоссарии, она не будет применяться. См. статьюПеревод документов с использованием пользовательского глоссария

Создание маркеров доступа SAS для перевода документов

Параметры sourceUrl, targetUrl и необязательный glossaryUrl должны включать маркер подписанного URL-адреса (SAS), добавленный в виде строки запроса. Маркер может быть назначен контейнеру или конкретным BLOB-объектам. См. статьюСоздание маркеров SAS для обработки перевода документов.

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

Совет

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

HTTP-запросы;

Запрос на перевод пакета документов отправляется в конечную точку службы переводчика через запрос POST. В случае успеха метод POST возвращает код отклика 202 Accepted, и пакетный запрос создается службой. Переведенные документы будут перечислены в контейнере целевых файлов.

Заголовки HTTP

В каждый запрос API перевода документов включены следующие заголовки.

Заголовок HTTP Описание
Ocp-Apim-Subscription-Key Обязательно. Это значение — ключ Azure для вашего переводчика или ресурса Cognitive Services.
Content-Type Обязательно. Указывает тип содержимого для полезных данных. Допустимые значения: application/json или charset = UTF-8.

Свойства текста запроса POST

  • URL-адрес запроса POST — POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches.
  • Текст запроса POST представляет собой объект JSON с именем inputs.
  • Объект inputs содержит адреса контейнеров sourceURL и targetURL для пар исходного и целевого языков.
  • prefix и suffix — это строки с учетом регистра для фильтрации документов, подлежащих переводу, в исходном пути. Поле prefix часто используется для обозначения вложенных папок для перевода. Поле suffix чаще всего используется для указания расширений файлов.
  • Значение поля glossaries (необязательно) применяется при переводе документа.
  • Параметр targetUrl для каждого целевого языка должен быть уникальным.

Примечание

Если в целевом расположении уже существует файл с указанным именем, произойдет сбой задания.

Перевод всех документов в контейнере

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Перевод конкретного документа в контейнере

  • Укажите "storageType": "File"
  • Если вы не используете назначаемое системой управляемое удостоверение для проверки подлинности, убедитесь, что вы создали маркер SAS исходного URL-адреса & для конкретного BLOB-объекта или документа (не для контейнера)
  • Убедитесь, что имя целевого файла указано в целевом URL-адресе; маркер SAS по-прежнему предназначен для контейнера.
  • Пример запроса ниже демонстрирует перевод одного документа на два целевых языка.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source"
             },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Использование кода для отправки запросов на перевод документов

Настройка платформы написания кода

  • Создайте новый проект.
  • Замените файл Program.cs кодом C#, указанным ниже.
  • Задайте значения параметров конечной точки, ключа и URL-адреса контейнера в файле Program.cs.
  • Для обработки данных JSON добавьте пакет Newtonsoft.Json с помощью интерфейса командной строки .NET.
  • Запустите программу из каталога проекта.

Важно!

В приведенных ниже примерах кода вы жестко запрограммируете URL-адрес SAS. Обязательно удалите URL-адрес SAS из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например управляемое удостоверение Azure. Дополнительные сведения см. в статье о безопасности службы хранилища Azure.

Может потребоваться обновить следующие поля в зависимости от операции.

  • endpoint
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (идентификатор задания)

Поиск значения id

  • id задания можно найти в значении URL-адреса заголовка Operation-Location ответа метода POST. Последний параметр URL-адреса — это задание операции id .
Заголовок ответа URL-адрес результата
Operation-Location https://<ИМЯ-ВАШЕГО-РЕСУРСА>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • Для получения id задания перевода документа можно также использовать запрос GET Jobs.

Перевод документов


    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.Text;


    class Program
    {

        static readonly string route = "/batches";

        private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

        private static readonly string key = "<YOUR-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }

Получение форматов файлов

Список поддерживаемых форматов файлов. В случае успеха этот метод возвращает код ответа 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/documents/formats";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Получение состояния задания

Текущее состояние для одного задания и сводка по всем заданиям в запросе на перевод документов. В случае успеха этот метод возвращает код ответа 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Получение сведений о состоянии документа

Краткий обзор

Состояние определенного документа в запросе на перевод документов. В случае успеха этот метод возвращает код ответа 200 OK.


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/{id}/document/{documentId}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Удаление задания

Краткий обзор

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


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

Ограничения содержимого

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

attribute Ограничение
Размер документа ≤ 40 МБ
Общее число файлов ≤ 1000
Общий размер содержимого в пакете ≤ 250 МБ
Число целевых языков в пакете ≤ 10
Размер файла памяти перевода ≤ 10 МБ

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

Устранение неполадок

Основные коды состояния HTTP

Код состояния HTTP Описание Возможная причина
200 ОК Запрос выполнен успешно.
400 Ошибка запроса Обязательный параметр отсутствует, пустой или его значение равно нулю. Или переданное либо обязательному, либо необязательному параметру значение является недопустимым. Распространенной проблемой является слишком длинный заголовок.
401 Не авторизовано Запрос не авторизован. Убедитесь, что ваш ключ или маркер являются допустимыми и находятся в правильных регионах. При управлении подпиской на портале Azure убедитесь, что вы используете ресурс Переводчик для одной службы, а не ресурс Cognitive Services, предназначенный для нескольких служб.
429 Слишком много запросов Вы превысили квоту или частоту запросов, разрешенных для вашей подписки.
502 Недопустимый шлюз Проблема с сетью или сервером. Может также указывать на недопустимые заголовки.

Подробнее

Дальнейшие действия