Управляемые удостоверения для перевода документов

Статья
09/01/2024

Управляемые удостоверения для ресурсов Azure — это субъекты-службы, которые создают удостоверение Microsoft Entra и определенные разрешения для управляемых ресурсов Azure. Управляемые удостоверения — это более безопасный способ предоставления доступа к данным хранилища и замены требования к включению маркеров подписи общего доступа (SAS) с исходными и целевыми URL-адресами.

Снимок экрана: поток управляемых удостоверений (RBAC).

Управляемые удостоверения можно использовать для предоставления доступа к любому ресурсу, поддерживающему проверку подлинности Microsoft Entra, включая собственные приложения.
Чтобы предоставить доступ к ресурсу Azure, назначьте роль Azure управляемому удостоверению с помощью управления доступом на основе ролей Azure (Azure RBAC).
Дополнительная плата за использование управляемых удостоверений в Azure не взимается.

Внимание

При использовании управляемых удостоверений не включайте URL-адрес маркера SAS в HTTP-запросы, иначе запросы будут завершаться ошибкой. Использование управляемых удостоверений заменяет требование для включения маркеров подписи общего доступа (SAS) на URL-адреса источника и целевого объекта.
Чтобы использовать управляемые удостоверения для операций перевода документов, необходимо создать ресурс Переводчика в определенном географическом регионе Azure, например в восточной части США. Если для региона ресурса Переводчика задано значение Global, вы не можете использовать управляемое удостоверение для перевода документов. Маркеры подписанного URL-адреса (SAS) по-прежнему можно использовать для перевода документов.
Перевод документов поддерживается в плане обслуживания S1 standard (по мере использования) и C2, C3, C4 и D3 Volume Discount Plans. См. цены на службы ИИ Azure— Переводчик.

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

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

Действующая учетная запись Azure. Если ее нет, можно создать учетную запись бесплатно.
Ресурс Переводчика с одним обслуживанием (а не службы Azure AI), назначенный географическому региону, например западной части США. Подробные инструкции см. в статье "Создание ресурса служб искусственного интеллекта Azure".
Краткое представление об управлении доступом на основе ролей Azure сAzure RBAC помощью портал Azure.
Учетная запись Хранилище BLOB-объектов Azure в том же регионе, что и ресурс Переводчика. Кроме того, необходимо создать контейнеры для хранения и упорядочивания данных BLOB-объектов в учетной записи хранения.
Если учетная запись хранения находится за брандмауэром, необходимо включить следующую конфигурацию:
1. Откройте портал Azure и войдите в свою учетную запись Azure.
2. Выберите учетную запись хранения.
3. В группе "Безопасность и сеть" в левой области выберите "Сеть".
4. На вкладке "Брандмауэры и виртуальные сети" выберите "Включено" из выбранных виртуальных сетей и IP-адресов.
5. Отмените выбор всех флажков.
6. Убедитесь, что выбрана маршрутизация сети Майкрософт.
7. В разделе "Экземпляры ресурсов" выберите Microsoft.CognitiveServices/accounts в качестве типа ресурса и выберите ресурс Переводчика в качестве имени экземпляра.
8. Убедитесь, что установлен флажок разрешить службам Azure в списке доверенных служб доступ к этой учетной записи хранения. Дополнительные сведения об управлении исключениями см. в разделе "Настройка служба хранилища Azure брандмауэров и виртуальных сетей".
9. Выберите Сохранить.
  
  Примечание.
  
  Для распространения изменений сети может потребоваться до 5 минут.
Хотя доступ к сети теперь разрешен, ресурс Переводчика по-прежнему не может получить доступ к данным в вашей учетной записи хранения. Необходимо создать управляемое удостоверение и назначить определенную роль доступа ресурсу Переводчика.

Назначение управляемых удостоверений

Существует два типа управляемых удостоверений: назначаемые системой и назначаемые пользователем. В настоящее время Перевод документов поддерживает управляемое удостоверение, назначаемое системой.

Управляемое удостоверение, назначаемое системой, включается непосредственно в экземпляре службы. Оно не включено по умолчанию. Необходимо перейти к ресурсу и изменить параметр удостоверения.
Управляемое удостоверение, назначаемое системой, связано с ресурсом на протяжении всего его жизненного цикла. При удалении ресурса также удаляется управляемое удостоверение.

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

Включение управляемого удостоверения, назначаемого системой

Перед созданием, чтением или удалением BLOB-объектов необходимо предоставить ресурс Переводчику доступ к учетной записи хранения. После включения ресурса Переводчика с управляемым удостоверением, назначаемого системой, вы можете использовать управлениеAzure RBAC доступом на основе ролей Azure для предоставления переводчику доступа к контейнерам службы хранилища Azure.

Откройте портал Azure и войдите в свою учетную запись Azure.
Выберите ресурс Переводчика.
В группе управления ресурсами в левой области выберите "Удостоверение".
На вкладке " Назначаемая системой" включите переключатель "Состояние ".

Внимание

Назначаемое пользователем управляемое удостоверение не соответствует требованиям для сценария учетной записи хранения пакетной транскрибации. Обязательно включите управляемое удостоверение, назначаемое системой.
Выберите Сохранить.

Предоставление доступа к учетной записи хранения для ресурса Переводчика

Внимание

Чтобы назначить роль управляемого удостоверения, назначаемую системой, требуется разрешение Microsoft.Authorization/roleAssignments/write, например "Владелец" или "Администратор доступа пользователей" в области хранилища для ресурса хранилища.

Откройте портал Azure и войдите в свою учетную запись Azure.
Выберите ресурс Переводчика.
В группе управления ресурсами в левой области выберите "Удостоверение".
В разделе Разрешения выберите Назначения ролей Azure.
На открывшейся странице назначений ролей Azure выберите подписку в раскрывающемся меню и нажмите кнопку +Добавить назначение ролей.

Затем назначьте роль участника данных BLOB-объектов хранилища ресурсу службы Переводчика. Роль Участник для данных BLOB-объектов хранилища предоставляет Переводчику (который представлен этим управляемым удостоверением, назначаемым системой) доступ на чтение, запись и удаление самого контейнера больших двоичных объектов и данных в нем. Во всплывающем окне Добавление назначения ролей заполните поля, как указано ниже, и нажмите кнопку Сохранить.

Поле	Значение
Область применения	*Хранилище*.
Подписка	*Подписка, связанная с ресурсом хранилища*.
Ресурс	*Имя ресурса хранилища*.
Роль	*Участник для данных BLOB-объектов хранилища*.

Снимок экрана: страница добавления назначений ролей на портале Azure.

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

HTTP-запросы;

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

Заголовки

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

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

Текст запроса POST

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

Внимание

Если в целевом расположении уже существует файл с указанным именем, произойдет сбой задания. При использовании управляемых удостоверений не включайте URL-адрес маркера SAS с HTTP-запросами. При этом запросы завершаются ошибкой.

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

Этот пример текста запроса ссылается на исходный контейнер для перевода всех документов на целевой язык.

Дополнительные сведения см. в разделе параметров запроса.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

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

Этот пример текста запроса ссылается на один исходный документ, который будет переведен на два целевых языка.

Внимание

Помимо параметров запроса, указанных ранее, необходимо включить "storageType": "File". В противном случае предполагается, что исходный URL-адрес находится на уровне контейнера.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

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

Этот пример текста запроса ссылается на исходный контейнер для всех документов, которые будут переведены на целевой язык с помощью глоссария.

Дополнительные сведения см. в разделе параметров запроса.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Отлично! Вы только что узнали, как включить и использовать управляемое удостоверение, назначаемое системой. С управляемым удостоверением для ресурсов Azure и Azure RBACвы предоставили переводчику определенные права доступа к ресурсу хранилища, не включая маркеры SAS с HTTP-запросами.

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

Краткое руководство. Начало работы с переводом документов

Руководство. Доступ к служба хранилища Azure из веб-приложения с помощью управляемых удостоверений

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

Управляемые удостоверения для перевода документов

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

Назначение управляемых удостоверений

Включение управляемого удостоверения, назначаемого системой

Предоставление доступа к учетной записи хранения для ресурса Переводчика

HTTP-запросы;

Заголовки

Текст запроса POST

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

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

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

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

Обратная связь

Дополнительные ресурсы