Поделиться через

Программное использование REST API

  • Статья

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

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

Примечание.

Перевод документов поддерживается в стандартном плане обслуживания S1 (оплата по мере использования) и планах с объемными скидками C2, C3, C4 и D3. Смотрите цены на услуги ИИ Azure — Переводчик.

Чтобы начать, вам нужно:

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

  • Учетная запись хранения BLOB-объектов Azure. Кроме того, необходимо создать контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и целевых файлов:

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

  • Ресурс Переводчика:

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

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

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

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

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

      Примечание.

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

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

    6. Выберите Review + Create.

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

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

Получите вашу ключевую конечную точку и конечную точку пользовательского домена

  • Для запросов к службе Переводчика требуется ключ только для чтения и настраиваемая конечная точка для проверки подлинности доступа. Конечная точка настраиваемого домена — это URL-адрес, отформатированный с именем вашего ресурса, именем узла и подкаталогами Переводчика и доступный в портале Azure.

  1. Если вы создали новый ресурс, после его развертывания нажмите кнопку "Перейти к ресурсу". Если у вас есть ресурс перевода документа, перейдите непосредственно на страницу ресурсов.

  2. На левой границе в разделе Управление ресурсами выберите Ключи и конечная точка.

  3. Скопируйте и вставьте key и document translation endpoint в удобное место, например, в Microsoft Notepad. Для вызова API необходим только один ключ.

  4. Вы вставляете key и document translation endpoint в примеры кода для проверки подлинности вашего запроса в службе перевода документов.

    Снимок экрана: поле получения ключа в портал Azure.

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

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

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

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

Создайте контейнеры Azure Blob Storage

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

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

Примечание.

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

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

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

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

Совет

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

HTTP-запросы;

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

Подробные сведения об ограничениях запросов службы Azure AI Translator см. в разделе"Ограничения запросов на перевод документов".

Заголовки HTTP

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

Заголовок HTTP Описание
Ocp-Apim-Subscription-Key Обязательно. Это значение является ключом Azure для ресурса "Переводчик" или "Службы искусственного интеллекта Azure".
Тип контента Обязательно: Указывает тип содержимого полезной нагрузки. Допустимые значения: application/json или charset = UTF-8.

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

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

Примечание.

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

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

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

  • Укажите "storageType": "File".
  • Если для проверки подлинности не используется управляемое удостоверение, назначаемое системой, убедитесь, что вы создали исходный URL-адрес и маркеры SAS для конкретного большого двоичного объекта или документа (а не для контейнера).
  • Убедитесь, что вы указали целевое имя файла в рамках целевого URL-адреса, хотя маркер SAS по-прежнему предназначен для контейнера.
  • Этот пример запроса возвращает один документ, переведенный на два целевых языка.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

🆕 Перевод текста, внедренного в изображения в документах

Примечание.

  • Эта функция является необязательной и должна быть включена для каждого запроса на перевод.
  • Включение этой функции приведет к дополнительным затратам в зависимости от использования. Дополнительные сведения см. в статьео ценах на Azure AI Vision
  • Эта функция в настоящее время доступна только через API пакетного перевода документов.
  • Поддерживается только формат файла .docx.
  • Для использования этой функции требуется ресурс Служб искусственного интеллекта Azure (а не автономный ресурс Переводчика).

Конфигурация запроса

  • Использование необязательного translateTextWithinImage параметра в options поле

    • Тип данных: Логический (true или false)
    • Логическое значение по умолчанию .false Установите параметр true, чтобы включить перевод текста изображения.

  • Сведения о ответе. Если эта функция включена, в ответ включается дополнительная информация об обработке изображений.

    • totalImageScansSucceeded. Количество успешно переведенных сканирований изображений.

    • totalImageScansFailed. Количество сканирований изображений, которые не удалось обработать.

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

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

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

Внимание

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

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

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

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

  • Вы можете найти задание id в значении URL-адреса Operation-Location в заголовке ответа метода POST start-batch-translation. Буквенно-цифровой строкой, следующей за /document/ параметром, является задание idоперации:
Заголовок ответа URL-адрес ответа
Операция-Местоположение {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}
  • Вы также можете использовать запрос get-translations-status, чтобы получить список заданийперевода и их idсостояний.

Запуск асинхронного пакетного перевода


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


    class Program
    {

        static readonly string route = "?api-version={date}";

        private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";

        private static readonly string key = "{your-api-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(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/formats";

    static readonly string route = "?api-version={date}&type=document";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";

    static readonly string route = "?api-version={date}";

    private static readonly string key = "{your-api-key}";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(basePath + 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);
            }
}

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

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

Подробнее

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

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