次の方法で共有


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

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

マネージド ID のフロー (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 サービス プラン (従量課金制) および C2、C3、C4、D3 ボリューム割引プランでサポートされています。 「Azure AI 翻訳の価格」を "参照してください"。

前提条件

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

  • アクティブな Azure アカウント—お持ちでない場合は、無料でアカウントを作成できます

  • 米国西部などの地理的リージョンに割り当てられた単一サービス Translator リソース (マルチサービス Azure AI サービスとは異なる)。 詳細な手順については、「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 に付与できます。

  1. Azure portal に移動し、ご自分の Azure アカウントにサインインします。

  2. Translator リソースを選択します。

  3. 左側のペインの [リソース管理] グループで、[ID] を選択します。

  4. [システム割り当て済み] タブで、[状態] トグルをオンにします。

    スクリーンショット: Azure portal の [リソース管理] [ID] タブ。

    重要

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

  5. [保存] を選択します。

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

重要

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

  1. Azure portal に移動し、ご自分の Azure アカウントにサインインします。

  2. Translator リソースを選択します。

  3. 左側のペインの [リソース管理] グループで、[ID] を選択します。

  4. [アクセス許可] で、 [Azure ロールの割り当て] を選択します。

    スクリーンショット: Azure portal でシステム割り当てマネージド ID を有効にする。

  5. 開いた [Azure ロールの割り当て] ページで、ドロップダウン メニューからサブスクリプションを選択し、[+ ロールの割り当ての追加] を選択します。

    スクリーンショット: Azure portal の [Azure ロールの割り当て] ページ。

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

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

    スクリーンショット: Azure portal の [ロールの割り当ての追加] ページ。

  7. [ロールの割り当てが追加されました] 確認メッセージが表示されたら、ページを更新して追加されたロールの割り当てを確認します。

    スクリーンショット: [ロールの割り当てが追加されました] 確認ポップアップ メッセージ。

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

    スクリーンショット: [Azure ロールの割り当て] ウィンドウ。

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 オブジェクトには、ソースとターゲットの言語ペア用の sourceURLtargetURL のコンテナー アドレスが両方とも含まれています。 システム割り当てマネージド ID では、プレーンのストレージ アカウント URL (SAS やその他の追加なし) を使用します。 形式は https://<storage_account_name>.blob.core.windows.net/<container_name> です。
  • prefixsuffix のフィールド (省略可能) は、フォルダーを格納しているコンテナー内のドキュメントをフィルター処理するために使用されます。
  • 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 に付与しました。

次の手順