Программное использование ИНТЕРФЕЙСов REST API

  • Статья

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

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

Примечание.

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

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

Для начала работы необходимы перечисленные ниже компоненты и данные.

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

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

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

  • Ресурс Переводчика с одной службой (а не ресурс служб ИИ 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.

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

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

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

Примечание.

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

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

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

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

Совет

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

HTTP-запросы;

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

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

Заголовки HTTP

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

Заголовок HTTP Description
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"
                        }
                    ]
                }
            ]
        }
    ]
}

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

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

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

Внимание

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

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

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

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

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

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


    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 Description Возможная причина
200 OK Запрос выполнен успешно.
400 ошибка запроса Обязательный параметр отсутствует, пустой или его значение равно нулю. Или переданное либо обязательному, либо необязательному параметру значение является недопустимым. Распространенной проблемой является слишком длинный заголовок.
401 Не авторизовано Запрос не авторизован. Убедитесь, что ваш ключ или маркер являются допустимыми и находятся в правильных регионах. При управлении подпиской на портал Azure убедитесь, что вы используете ресурс с одним обслуживанием Переводчика, а не ресурс нескольких служб ИИ Azure.
429 Слишком много запросов Вы превысили квоту или частоту запросов, разрешенных для вашей подписки.
502 Недопустимый шлюз Проблема с сетью или сервером. Также может указывать недопустимые заголовки.

Подробнее

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

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