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

Статья
02/12/2024

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

Screenshot of managed identity flow (RBAC).

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

Внимание

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

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

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

Действующая учетная запись Azure. Если ее нет, можно создать учетную запись бесплатно.
Ресурс с одним Переводчик (а не несколькими службами ИИ 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.

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

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

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

Внимание

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

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

Внимание

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

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

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

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

Screenshot: add role assignments page in the Azure portal.

После появления сообщения подтверждения назначения добавленной роли обновите страницу, чтобы увидеть добавление назначения ролей.
Если новое назначение роли не отображается сразу, подождите и повторите попытку обновления страницы. При добавлении или удалении назначений ролей может потребоваться до 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

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

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

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

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

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