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

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

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

Примечание

  1. Обычно при создании ресурсов Cognitive Service на портале Azure у вас есть возможность создать ключ подписки на несколько служб или ключ подписки на одну службу. Однако перевод документов в настоящее время поддерживается только в ресурсе Переводчик (только одна служба) и не включен в ресурс Cognitive Services (несколько служб).
  2. Перевод документов доступен только в плане обслуживания "Стандартный" S1 (с оплатой по мере использования) или в плане оптовых скидок D3. см.Cognitive Services цены — Переводчик.

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

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

Важно!

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

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

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

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

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

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

Image of the Azure portal, create resource, instant details, name field.

Получение ключа подписки

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

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

Image of the get your subscription key field in Azure portal.

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

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

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

Примечание

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

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

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

  • Исходный контейнер или большой двоичный объект должен иметь назначенный доступ для чтения и получения списка .
  • Целевой контейнер или большой двоичный объект должен иметь назначенный доступ на запись и список .
  • Большой двоичный объект глоссария должен иметь назначенный доступ для чтения и получения списка .

Совет

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

Перевод документов: HTTP-запросы

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

Заголовки HTTP

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

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

Свойства текста запроса 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 (необязательно) используются для фильтрации документов в контейнере, включая папки.
  • Значение 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-адреса & для конкретного большого двоичного объекта или документа (не для контейнера).
  • Убедитесь, что имя целевого файла указано в целевом 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",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "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.
  • Запустите программу из каталога проекта.

Важно!

В приведенных ниже примерах кода вы жестко программируете ключ и конечную точку, где указано; не забудьте удалить ключ из кода по завершении и никогда не публикуйте его в общем доступе. Способы безопасного хранения и доступа к учетным данным см. в статье Безопасность Azure Cognitive Services.

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

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (ИД задания)

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

  • Задание можно найти id в Operation-Location значении URL-адреса заголовка ответа метода POST. Последний параметр URL-адреса — это задание операции id .
Заголовок ответа URL-адрес результата
Operation-Location https:// <<
  • Для получения задания перевода документа можно также использовать запрос на Получение заданий .

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


    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 subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"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", subscriptionKey);
                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 subscriptionKey = "<YOUR-SUBSCRIPTION-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", subscriptionKey);


                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 subscriptionKey = "<YOUR-SUBSCRIPTION-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", subscriptionKey);


                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 subscriptionKey = "<YOUR-SUBSCRIPTION-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", subscriptionKey);


                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 subscriptionKey = "<YOUR-SUBSCRIPTION-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", subscriptionKey);


                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 Недопустимый шлюз Проблема с сетью или сервером. Может также указывать на недопустимые заголовки.

Подробнее

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