ドキュメント翻訳のマネージド ID

[アーティクル]
02/12/2024

Azure リソースのマネージド ID は、Microsoft Entra ID と、Azure 管理対象リソースに対する特定のアクセス許可を作成するサービスプリンシパルです。マネージド ID は、ストレージデータへのアクセスを許可し、ソース URL とターゲット URL に Shared Access Signature トークン (SAS) を含めるように要件を置き換えるためのより安全な方法です。

Screenshot of managed identity flow (RBAC).

マネージド ID を使用すると、独自のアプリケーションを含む、Microsoft Entra 認証をサポートする任意のリソースへのアクセス権を付与できます。
Azure リソースにアクセス権を付与するには、Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、マネージド ID に Azure ロールを割り当てます。
Azure でマネージド ID を使用するために追加コストはかかりません。

重要

マネージド ID を使用する場合、HTTP 要求に SAS トークン URL を含めないでください。要求は失敗します。マネージド ID を使用すると、Shared Access Signature Token (SAS) をソース URL とターゲット URL に含めるという要件が置き換えられます。
ドキュメント翻訳操作にマネージド ID を使用するには、米国東部などの特定の地理的 Azure リージョンに Translator リソースを作成する必要があります。 Translator リソースリージョンがグローバルに設定されている場合、ドキュメント翻訳にはマネージド ID を使用できません。ドキュメント翻訳には、引き続き Shared Access Signature トークン (SAS) を使用できます。
ドキュメント翻訳は、現在、S1 Standard サービスプラン (従量料金) または D3 ボリューム割引プランのみでご利用いただけます。「Azure AI サービスの価格 - Translator」をご覧ください。

前提条件

開始するには、以下が必要です。

アクティブな Azure アカウント—お持ちでない場合は、無料でアカウントを作成できます。
米国西部などの地理的リージョンに割り当てられた単一サービス Translator リソース (マルチサービス Azure AI サービスとは異なる)。詳細な手順については、「マルチサービスリソースを作成する」を参照してください。
Azure portal で使用する Azure ロールベースのアクセス制御 (Azure RBAC) の概要の理解。
Translator リソースと同じリージョンにある Azure Blob Storage アカウント。また、ストレージアカウント内に BLOB データを格納して整理するためのコンテナーを作成する必要があります。
ストレージアカウントがファイアウォールの内側にある場合、次の構成を有効にする必要があります。
1. Azure portal に移動し、ご自分の Azure アカウントにサインインします。
2. ストレージアカウントを選択します。
3. 左側のペインの [セキュリティとネットワーク] グループで、[ネットワーク] を選択します。
4. [ファイアウォールと仮想ネットワーク] タブで、[選択した仮想ネットワークと IP アドレスから有効] を選択します。
5. すべてのチェックボックスの選択を解除します。
6. [Microsoft ネットワークルーティング] が選択されていることを確認します。
7. [リソースインスタンス] セクションで、リソースの種類として Microsoft.CognitiveServices/accounts を選択し、ご利用の Translator リソースをインスタンス名として選択します。
8. [信頼されたサービスの一覧にある Azure サービスがこのストレージアカウントにアクセスすることを許可します] ボックスがオンになっていることを確認します。例外の管理に関する詳細については、「Azure Storage ファイアウォールおよび仮想ネットワークを構成する」を参照してください。
9. [保存] を選択します。
  
  注意
  
  ネットワークの変更が反映されるまでに最大 5 分かかる場合があります。
ネットワークアクセスは許可されていますが、Translator リソースはまだストレージアカウントのデータにアクセスできません。 Translator リソースのマネージド ID を作成し、特定のアクセスロールを割り当てる必要があります。

マネージド ID の割り当て

マネージド ID には、システム割り当てとユーザー割り当ての 2 種類があります。現在、ドキュメント翻訳では、システム割り当てマネージド ID がサポートされています。

システム割り当てマネージド ID は、サービスインスタンス上で直接有効化されます。既定では有効になっていないため、リソースにアクセスして、ID 設定を更新する必要があります。
システム割り当てマネージド ID は、ライフサイクル全体を通してリソースに関連付けされます。リソースを削除すると、マネージド ID も削除されます。

以下の手順では、システム割り当てマネージド ID を有効にし、Translator リソースに Azure Blob Storage アカウントへの制限付きアクセスを許可します。

システム割り当てマネージド ID を有効にする

Translator リソースには、BLOB の作成、読み取り、削除を行えるように、あらかじめストレージアカウントへのアクセスを許可しておく必要があります。システム割り当てマネージド ID のある Translator リソースを有効にしたら、Azure のロールベースのアクセス制御 (Azure RBAC) を使用して、ご利用の Azure ストレージコンテナーへのアクセス権を Translator に付与できます。

Azure portal に移動し、ご自分の Azure アカウントにサインインします。
Translator リソースを選択します。
左側のペインの [リソース管理] グループで、[ID] を選択します。
[システム割り当て済み] タブで、[状態] トグルをオンにします。

重要

ユーザー割り当てマネージド ID は、バッチ文字起こしストレージアカウントシナリオの要件を満たしません。必ずシステム割り当てマネージド ID を有効にするようにしてください。
[保存] を選択します。

Translator リソースにストレージアカウントへのアクセスを許可する

重要

システム割り当てマネージド ID ロールを割り当てるには、ストレージリソースのストレージスコープで、所有者やユーザーアクセス管理者などの Microsoft.Authorization/roleAssignments/write アクセス許可が必要です。

Azure portal に移動し、ご自分の Azure アカウントにサインインします。
Translator リソースを選択します。
左側のペインの [リソース管理] グループで、[ID] を選択します。
[アクセス許可] で、 [Azure ロールの割り当て] を選択します。
開いた [Azure ロールの割り当て] ページで、ドロップダウンメニューからサブスクリプションを選択し、[+ ロールの割り当ての追加] を選択します。

次に、Translator サービスリソースにストレージ BLOB データ共同作成者ロールを割り当てます。 ストレージ BLOB データ共同作成者ロールにより、(システム割り当てマネージド ID で表される) Translator に、BLOB コンテナーとデータへの読み取り、書き込み、削除アクセス権が付与されます。 [ロールの割り当ての追加] ポップアップウィンドウで、以下のようにフィールドに入力して、 [保存] を選択します。

フィールド	値
スコープ	*Storage*。
サブスクリプション	*ストレージリソースに関連付けられているサブスクリプション*。
リソース	*ストレージリソースの名前*。
ロール	*ストレージ BLOB データ共同作成者*。

Screenshot: add role assignments page in the Azure portal.

[ロールの割り当てが追加されました] 確認メッセージが表示されたら、ページを更新して追加されたロールの割り当てを確認します。
新しいロールの割り当てがすぐに表示されない場合は、もう一度ページを更新してみてください。ロールを割り当てたり、ロールの割り当てを削除したりした場合、変更が適用されるまでに最大 30 分かかることがあります。

HTTP 要求

非同期バッチ翻訳要求は、POST 要求を通じて Translator サービスエンドポイントに送信されます。
マネージド ID と Azure RBAC を使用すると、SAS URL を含める必要はなくなります。
成功した場合、POST メソッドから 202 Accepted 応答コードが返され、サービスによってバッチ要求が作成されます。
翻訳されたドキュメントがターゲットコンテナーに表示されます。

ヘッダー

各 Document Translation API 要求には、次のヘッダーが含まれています。

HTTP ヘッダー	説明
Ocp-Apim-Subscription-Key	必須: 値は、Translator または Azure AI サービスリソースの Azure キーです。
Content-Type	必須: ペイロードのコンテンツタイプを指定します。許容される値は、application/json または charset=UTF-8 です。

POST 要求本文

要求 URL は POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches です。
要求本文は、inputs という名前の JSON オブジェクトです。
inputs オブジェクトには、ソースとターゲットの言語ペア用の sourceURL と targetURL のコンテナーアドレスが両方とも含まれています。システム割り当てマネージド ID では、プレーンのストレージアカウント URL (SAS やその他の追加なし) を使用します。形式は https://<storage_account_name>.blob.core.windows.net/<container_name> です。
prefix と suffix のフィールド (省略可能) は、フォルダーを格納しているコンテナー内のドキュメントをフィルター処理するために使用されます。
glossaries フィールド (省略可能) の値は、ドキュメントが翻訳されるときに適用されます。
各ターゲット言語の targetUrl は一意でなければなりません。

重要

同じ名前のファイルが宛先に既に存在する場合、ジョブは失敗します。マネージド ID を使用する場合、HTTP 要求に SAS トークン URL を含めないでください。含めると、要求は失敗します。

コンテナー内のすべてのドキュメントを翻訳する

このサンプルの要求本文は、ターゲット言語に翻訳されるすべてのドキュメントのソースコンテナーを参照します。

詳細については、「要求パラメーター」を参照してください。

{
    "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"
                }
            ]
        }
    ]
}

コンテナー内の特定のドキュメントを翻訳する

このサンプルの要求本文は、2 つのターゲット言語に翻訳される 1 つのソースドキュメントを参照します。

重要

前述の要求パラメーターに加えて、"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"
                        }
                    ]
                }
            ]
        }
    ]
}

完了。システム割り当てマネージド ID を有効にして使う方法を学習しました。 Azure リソースのマネージド ID と Azure RBAC により、HTTP 要求に SAS トークンを含めずに、ストレージリソースへの特定のアクセス権を Translator に付与しました。

次の手順

クイックスタート: ドキュメント翻訳を使ってみる

チュートリアル: マネージド ID を使用して Web アプリから Azure Storage にアクセスする