クイックスタート: Azure AI サービスのマルチサービス リソースを作成する

Azure AI サービスのマルチサービス リソースを作成および管理する方法について説明します。 マルチサービス リソースを使用すると、1 つのキーとエンドポイントを使用して複数の Azure AI サービスにアクセスできます。 また、ご利用の複数のサービスの課金が統合されます。

Azure AI サービスには 2 つの異なるリソース (マルチサービス リソースとシングルサービス リソース) を通じてアクセスできます。

• マルチサービス リソース:
  • 1 つのキーとエンドポイントを使用して複数の Azure AI サービスにアクセスします。
  • ご利用の複数のサービスの課金を統合します。
• 単一サービス リソース:
  • 作成されたサービスごとに一意のキーとエンドポイントを使用して、単一の Azure AI サービスにアクセスします。
  • ほとんどの Azure AI サービスには、試用のための Free レベルが用意されています。

Azure AI サービスは、ご利用の Azure サブスクリプションに作成した Azure リソースです。 リソースの作成後、生成されたキーとエンドポイントを使用して、アプリケーションを認証できます。

マルチサービス リソースでサポートされているサービス

マルチサービス リソースを使用すると、1 つのキーとエンドポイントを使用して、以下の Azure AI サービスにアクセスできます。 リソースの使用を開始する方法については、以下のリンクからクイックスタート記事やサンプルなどを参照してください。

サービス	説明
Content Moderator (廃止)	不快感を与える可能性がある、または望ましくないコンテンツを検出する。
Custom Vision	画像認識をビジネス用にカスタマイズします。
Document Intelligence	ドキュメントをインテリジェントなデータ ドリブン ソリューションに変換します。
Face	画像内の人や感情を検出および識別します。
Language	業界をリードする自然言語理解機能を備えたアプリを構築します。
Speech	音声テキスト変換、テキスト読み上げ、翻訳、話者認識。
Translator	AI を利用した翻訳テクノロジを使用して、100 を超える使用中の言語、危険にさらされている言語、消滅の危機に瀕している言語や方言を翻訳します。
Vision	画像と動画のコンテンツを分析します。

前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。

新しいマルチサービス リソースを作成する

マルチサービス リソースは、ポータルの [Azure AI サービス]>[Azure AI サービス マルチサービス アカウント] の下に一覧表示されます。 マルチサービス リソースを作成するには、以下の手順を実行します。

1. マルチサービス リソースを作成するには、次のリンクを選択します。https://portal.azure.com/#create/Microsoft.CognitiveServicesAllInOne

2. [作成] ページで、次の情報を指定します。

   プロジェクトの詳細	説明
   サブスクリプション	使用できる Azure サブスクリプションのいずれかを選択します。
   リソース グループ	Azure AI サービス リソースを含める Azure リソース グループ。 新しいグループを作成することも、既存のグループに追加することもできます。
   リージョン	Azure AI サービス インスタンスの場所。 別の場所を選択すると待機時間が生じる可能性がありますが、リソースのランタイムの可用性には影響しません。
   名前	Azure AI サービス リソースのわかりやすい名前。 例: MyCognitiveServicesResource。
   価格レベル	Azure AI サービス アカウントのコストは、選択しているオプションと使用量によって異なります。 詳細については、「API の価格の詳細」をご覧ください。

   

3. 必要に応じてリソースの他の設定を構成し、条件を読み取って同意し (該当する場合)、[Review + create(確認と作成) ] を選択します。

ヒント

サブスクリプションで Azure AI サービス リソースの作成が許可されていない場合は、Azure portal、PowerShell コマンド、または Azure CLI コマンドを使用して、その Azure リソース プロバイダーの特権を有効にする必要がある場合があります。 サブスクリプションの所有者でない場合は、サブスクリプションの所有者、または管理者のロールを持つユーザーに、登録の完了を要求するか、アカウントに /register/action 特権を付与するように要求します。

リソースのキーを取得する

1. リソースが正常にデプロイされたら、[Next Steps(次のステップ )] >[Go to resource(リソースへの移行)] を選択します。

   

2. 開かれた [クイックスタート] ウィンドウから、リソースエンドポイントにアクセスしキーを管理できます。

認証用の環境変数を構成する

Azure AI サービス リソースにアクセスするには、アプリケーションを認証する必要があります。 リソース キーの環境変数を設定するには、コンソール ウィンドウを開き、オペレーティング システムと開発環境の指示に従います。 COGNITIVE_SERVICE_KEY 環境変数を設定するには、your-key をリソースのキーの 1 つに置き換えます。

運用環境では、パスワードで保護されたシークレット コンテナーなどの資格情報を格納してアクセスする安全な方法を使用します。 テストの場合、環境変数への書き込みは標準的な方法ですが、環境変数はローカル コンピューター上のクリア テキストに格納されます。

ヒント

キーは、コードに直接含めないようにし、公開しないでください。 Azure Key Vault などのその他の認証オプションについては、Azure AI サービスのセキュリティに関する記事を参照してください。

Windows

PowerShell には、シークレット ストアや Azure KeyVault などのプラットフォームにセキュリティで保護された文字列を格納するための拡張可能なソリューションであるシークレットの管理が含まれています。

セキュリティで保護された文字列をホストするようにシークレット ストアを設定するには、シークレット ストアの使用の概要に関する記事を参照してください。 その後、次の例を使用して API キーを格納します。

Set-Secret -Name COGNITIVE_SERVICE_KEY -value your-key

テスト環境の場合は、PowerShell の $Env: 構文を使用して現在のセッションのみに環境変数を設定するか、setx コマンドを使用してセッション間で変数を保持することができます。 これらの値は、Windows レジストリ キーのクリア テキストに格納されていることに注意してください。

$Env:COGNITIVE_SERVICE_KEY = your-key

setx COGNITIVE_SERVICE_KEY your-key

setx を使用する環境変数を追加した後に、環境変数を読み取る必要がある実行中のコンソールまたは他のプログラムの再起動が必要になる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

Linux

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bashrc を実行します。

macOS

Bash

次のように .bash_profile を編集し、環境変数を追加します。

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bash_profile を実行します。

Xcode

iOS と macOS の開発では、Xcode で環境変数を設定します。 たとえば、次の手順に従って、Xcode 13.4.1 で環境変数を設定します。

1. [Product]、[Scheme]、[スキームの編集] の順に選択する
2. [引数] を [実行] (デバッグ実行) ページで選択する
3. [環境変数] で、プラス記号 (+) を選択して、新しい環境変数を追加します。
4. [名前] に「COGNITIVE_SERVICE_KEY」と入力し、[値] にリソース キーを入力します。

その他の構成オプションについては、Xcode のドキュメントを参照してください。

Azure Cognitive Service for Speech リソース リージョンの環境変数を設定するには、同じ手順に従います。 リソースのリージョンに COGNITIVE_SERVICE_REGION を設定します。 たとえば、「 westus 」のように入力します。

リソースをクリーンアップする

Azure AI サービス サブスクリプションをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除することができます。 リソース グループを削除すると、そのグループに含まれている他のリソースも削除されます。

1. Azure Portal で左側のメニューを展開してサービスのメニューを開き、 [リソース グループ] を選択して、リソース グループの一覧を表示します。
2. 削除するリソースが含まれているリソース グループを見つけます。
3. リソース グループ全体を削除する場合は、リソース グループ名を選択します。 次のページで [リソース グループの削除] を選択し、確認します。
4. Azure AI サービス リソースのみを削除する場合は、リソース グループを選択して、その中のすべてのリソースを表示します。 次のページで、削除するリソースを選択し、その行の省略記号メニューを選択して、[削除] を選択します。

このクイックスタートでは、Azure コマンド ライン インターフェイス (CLI) のコマンドを使用して、Azure AI サービス リソースを作成します。 リソースの作成後、生成されたキーとエンドポイントを使用して、アプリケーションを認証します。

Azure AI サービスは、開発者が直接的な人工知能 (AI) またはデータ サイエンスのスキルや知識がなくてもコグニティブかつインテリジェントなアプリケーションを構築できる、クラウドベースの AI サービスです。 これらは、REST API とクライアント ライブラリ SDK を通じて、一般的な開発言語で利用できます。 開発者は Azure AI サービスを使用して、見たり、聞いたり、話したり、分析したりできるコグニティブ ソリューションを使用したコグニティブ機能をそのアプリケーションに容易に追加することができます。

前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成します。
• Azure CLI
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure CLI をインストールしてサインインする

Azure CLI をインストールします。 CLI のローカル インストールにサインインするには、az login コマンドを実行します。

az login

また、緑色の [使ってみる] ボタンを使用して、お使いのブラウザーでこれらのコマンドを実行することもできます。

新しい Azure AI サービス リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループを用意する必要があります。 新しいリソースを作成するときは、新しいリソース グループを作成するか、既存のものを使用できます。 この記事では、新しいリソース グループを作成する方法を示します。

リソース グループの場所を選択する

リソースを作成するには、お使いのサブスクリプションに使用できるいずれかの Azure の場所が必要です。 使用できる場所の一覧を取得するには、az account list-locations コマンドを使用します。 ほとんどの Azure AI サービスは複数の場所からアクセスできます。 お客様に最も近いものを選択するか、サービスに使用できる場所を確認します。

重要

• Azure AI サービス リソースを呼び出すときに必要になるので、Azure の場所は記憶しておいてください。
• 一部の Azure AI サービスは、リージョンによって使用可能かどうかが異なります。 詳細については、「リージョン別の Azure 製品」を参照してください。

az account list-locations --query "[].{Region:name}" --out table

Azure の場所が決まったら、Azure CLI で az group create コマンドを使用して新しいリソース グループを作成します。 次の例では、Azure の場所 westus2 を、お使いのサブスクリプションで使用できる Azure の場所の 1 つに置き換えます。

az group create --name ai-services-resource-group --location westus2

Azure AI サービス リソースを作成する

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの種類と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

使用できる Azure AI サービスの "種類" のリストを確認するには、az cognitiveservices account list-kinds コマンドを使用します。

az cognitiveservices account list-kinds

リソース グループに新しいリソースを追加する

新しい Azure AI サービス リソースを作成してサブスクライブするには、az cognitiveservices account create コマンドを使用します。 このコマンドで、以前に作成したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。

次のコマンドを使用して、multi-service-resource という名前の Standard S0 マルチサービス リソースを作成できます。

az cognitiveservices account create --name multi-service-resource --resource-group ai-services-resource-group  --kind CognitiveServices --sku F0 --location westus2 --yes

ヒント

サブスクリプションで Azure AI サービス リソースの作成が許可されていない場合は、Azure portal、PowerShell コマンド、または Azure CLI コマンドを使用して、その Azure リソース プロバイダーの特権を有効にする必要がある場合があります。 サブスクリプションの所有者でない場合は、サブスクリプションの所有者、または管理者のロールを持つユーザーに、登録の完了を要求するか、アカウントに /register/action 特権を付与するように要求します。

リソースのキーを取得する

コマンドライン インターフェイス (CLI) のローカル インストールにログインするには、az login コマンドを使用します。

az login

リソースのキーを取得するには、az cognitiveservices account keys list コマンドを使用します。

az cognitiveservices account keys list  --name multi-service-resource --resource-group ai-services-resource-group

認証用の環境変数を構成する

Azure AI サービス リソースにアクセスするには、アプリケーションを認証する必要があります。 リソース キーの環境変数を設定するには、コンソール ウィンドウを開き、オペレーティング システムと開発環境の指示に従います。 COGNITIVE_SERVICE_KEY 環境変数を設定するには、your-key をリソースのキーの 1 つに置き換えます。

運用環境では、パスワードで保護されたシークレット コンテナーなどの資格情報を格納してアクセスする安全な方法を使用します。 テストの場合、環境変数への書き込みは標準的な方法ですが、環境変数はローカル コンピューター上のクリア テキストに格納されます。

ヒント

キーは、コードに直接含めないようにし、公開しないでください。 Azure Key Vault などのその他の認証オプションについては、Azure AI サービスのセキュリティに関する記事を参照してください。

Windows

PowerShell には、シークレット ストアや Azure KeyVault などのプラットフォームにセキュリティで保護された文字列を格納するための拡張可能なソリューションであるシークレットの管理が含まれています。

セキュリティで保護された文字列をホストするようにシークレット ストアを設定するには、シークレット ストアの使用の概要に関する記事を参照してください。 その後、次の例を使用して API キーを格納します。

Set-Secret -Name COGNITIVE_SERVICE_KEY -value your-key

テスト環境の場合は、PowerShell の $Env: 構文を使用して現在のセッションのみに環境変数を設定するか、setx コマンドを使用してセッション間で変数を保持することができます。 これらの値は、Windows レジストリ キーのクリア テキストに格納されていることに注意してください。

$Env:COGNITIVE_SERVICE_KEY = your-key

setx COGNITIVE_SERVICE_KEY your-key

setx を使用する環境変数を追加した後に、環境変数を読み取る必要がある実行中のコンソールまたは他のプログラムの再起動が必要になる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

Linux

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bashrc を実行します。

macOS

Bash

次のように .bash_profile を編集し、環境変数を追加します。

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bash_profile を実行します。

Xcode

iOS と macOS の開発では、Xcode で環境変数を設定します。 たとえば、次の手順に従って、Xcode 13.4.1 で環境変数を設定します。

1. [Product]、[Scheme]、[スキームの編集] の順に選択する
2. [引数] を [実行] (デバッグ実行) ページで選択する
3. [環境変数] で、プラス記号 (+) を選択して、新しい環境変数を追加します。
4. [名前] に「COGNITIVE_SERVICE_KEY」と入力し、[値] にリソース キーを入力します。

その他の構成オプションについては、Xcode のドキュメントを参照してください。

Azure Cognitive Service for Speech リソース リージョンの環境変数を設定するには、同じ手順に従います。 リソースのリージョンに COGNITIVE_SERVICE_REGION を設定します。 たとえば、「 westus 」のように入力します。

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この量を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

現在のリソースのクォータ使用量を取得する

リソースのキーを取得するには、az cognitiveservices account list-usage コマンドを使用します。

az cognitiveservices account list-usage --name multi-service-resource --resource-group ai-services-resource-group --subscription subscription-name

リソースをクリーンアップする

Azure AI サービス リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除することができます。 リソース グループを削除すると、そのグループに含まれている他のリソースも削除されます。

リソース グループとそれに関連付けられているリソースを削除するには、az group delete コマンドを使用します。

az group delete --name ai-services-resource-group

このクイックスタートでは、Azure PowerShell コマンドを使用して、Azure AI サービス リソースを作成します。 リソースの作成後、生成されたキーとエンドポイントを使用して、アプリケーションを認証します。

Azure AI サービスは、開発者が直接的な人工知能 (AI) またはデータ サイエンスのスキルや知識がなくてもコグニティブかつインテリジェントなアプリケーションを構築できる、クラウドベースの AI サービスです。 これらは、REST API とクライアント ライブラリ SDK を通じて、一般的な開発言語で利用できます。 開発者は Azure AI サービスを使用して、見たり、聞いたり、話したり、分析したりできるコグニティブ ソリューションを使用したコグニティブ機能をそのアプリケーションに容易に追加することができます。

前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• Azure PowerShell
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure PowerShell をインストールして Azure にサインインします。

Azure PowerShellをインストールします。 サインインするには、Connect-AzAccount コマンドを実行します。

Connect-AzAccount

また、緑色の [使ってみる] ボタンを使用して、お使いのブラウザーでこれらのコマンドを実行することもできます。

新しい Azure AI サービス リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループを用意する必要があります。 新しいリソースを作成するときは、新しいリソース グループを作成するか、既存のものを使用できます。 この記事では、新しいリソース グループを作成する方法を示します。

リソース グループの場所を選択する

リソースを作成するには、お使いのサブスクリプションに使用できるいずれかの Azure の場所が必要です。 使用できる場所の一覧を取得するには、Get-AzLocation コマンドを使用します。 ほとんどの Azure AI サービスは複数の場所からアクセスできます。 お客様に最も近いものを選択するか、サービスに使用できる場所を確認します。

重要

• Azure AI サービス リソースを呼び出すときに必要になるので、Azure の場所は記憶しておいてください。
• 一部の Azure AI サービスは、リージョンによって使用可能かどうかが異なります。 詳細については、「リージョン別の Azure 製品」を参照してください。

Get-AzLocation | Select-Object -Property Location, DisplayName

Azure の場所が決まったら、Azure PowerShell で New-AzResourceGroup コマンドを使用して新しいリソース グループを作成します。 次の例では、Azure の場所 westus2 を、お使いのサブスクリプションで使用できる Azure の場所の 1 つに置き換えます。

New-AzResourceGroup -Name ai-services-resource-group -Location westus2

Azure AI サービス リソースを作成する

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの種類と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

使用できる Azure AI サービスの "種類" のリストを確認するには、Get-AzCognitiveServicesAccountType コマンドを使用します。

Get-AzCognitiveServicesAccountType

リソース グループに新しいリソースを追加する

新しい Azure AI サービス リソースを作成してサブスクライブするには、New-AzCognitiveServicesAccount コマンドを使用します。 このコマンドで、以前に作成したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。

次のコマンドを使用して、multi-service-resource という名前の Standard S0 マルチサービス リソースを作成できます。

New-AzCognitiveServicesAccount -ResourceGroupName ai-services-resource-group -Name multi-service-resource -Type CognitiveServices -SkuName F0 -Location westus2

ヒント

サブスクリプションで Azure AI サービス リソースの作成が許可されていない場合は、Azure portal、Azure PowerShell コマンド、または Azure CLI コマンドを使用して、その Azure リソース プロバイダーの特権を有効にする必要がある場合があります。 サブスクリプションの所有者でない場合は、サブスクリプションの所有者、または管理者のロールを持つユーザーに、登録の完了を要求するか、アカウントに /register/action 特権を付与するように要求します。

リソースのキーを取得する

リソースのキーを取得するには、Get-AzCognitiveServicesAccountKey コマンドを使用します。

Get-AzCognitiveServicesAccountKey -Name multi-service-resource -ResourceGroupName ai-services-resource-group

認証用の環境変数を構成する

Azure AI サービス リソースにアクセスするには、アプリケーションを認証する必要があります。 リソース キーの環境変数を設定するには、コンソール ウィンドウを開き、オペレーティング システムと開発環境の指示に従います。 COGNITIVE_SERVICE_KEY 環境変数を設定するには、your-key をリソースのキーの 1 つに置き換えます。

運用環境では、パスワードで保護されたシークレット コンテナーなどの資格情報を格納してアクセスする安全な方法を使用します。 テストの場合、環境変数への書き込みは標準的な方法ですが、環境変数はローカル コンピューター上のクリア テキストに格納されます。

ヒント

キーは、コードに直接含めないようにし、公開しないでください。 Azure Key Vault などのその他の認証オプションについては、Azure AI サービスのセキュリティに関する記事を参照してください。

Windows

PowerShell には、シークレット ストアや Azure KeyVault などのプラットフォームにセキュリティで保護された文字列を格納するための拡張可能なソリューションであるシークレットの管理が含まれています。

セキュリティで保護された文字列をホストするようにシークレット ストアを設定するには、シークレット ストアの使用の概要に関する記事を参照してください。 その後、次の例を使用して API キーを格納します。

Set-Secret -Name COGNITIVE_SERVICE_KEY -value your-key

テスト環境の場合は、PowerShell の $Env: 構文を使用して現在のセッションのみに環境変数を設定するか、setx コマンドを使用してセッション間で変数を保持することができます。 これらの値は、Windows レジストリ キーのクリア テキストに格納されていることに注意してください。

$Env:COGNITIVE_SERVICE_KEY = your-key

setx COGNITIVE_SERVICE_KEY your-key

setx を使用する環境変数を追加した後に、環境変数を読み取る必要がある実行中のコンソールまたは他のプログラムの再起動が必要になる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

Linux

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bashrc を実行します。

macOS

Bash

次のように .bash_profile を編集し、環境変数を追加します。

export COGNITIVE_SERVICE_KEY=your-key

環境変数を追加した後、変更を有効にするには、コンソール ウィンドウから source ~/.bash_profile を実行します。

Xcode

iOS と macOS の開発では、Xcode で環境変数を設定します。 たとえば、次の手順に従って、Xcode 13.4.1 で環境変数を設定します。

1. [Product]、[Scheme]、[スキームの編集] の順に選択する
2. [引数] を [実行] (デバッグ実行) ページで選択する
3. [環境変数] で、プラス記号 (+) を選択して、新しい環境変数を追加します。
4. [名前] に「COGNITIVE_SERVICE_KEY」と入力し、[値] にリソース キーを入力します。

その他の構成オプションについては、Xcode のドキュメントを参照してください。

Azure Cognitive Service for Speech リソース リージョンの環境変数を設定するには、同じ手順に従います。 リソースのリージョンに COGNITIVE_SERVICE_REGION を設定します。 たとえば、「 westus 」のように入力します。

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この量を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

現在のリソースのクォータ使用量を取得する

リソースのキーを取得するには、Get-AzCognitiveServicesAccountUsage コマンドを使用します。

Get-AzCognitiveServicesAccountUsage -ResourceGroupName ai-services-resource-group -Name multi-service-resource

リソースをクリーンアップする

Azure AI サービス リソースをクリーンアップして削除したい場合は、リソースまたはリソース グループを削除することができます。 リソース グループを削除すると、そのグループに含まれている他のリソースも削除されます。

リソース グループとそれに関連付けられているリソースを削除するには、Remove-AzResourceGroup コマンドを使用します。

Remove-AzResourceGroup -Name ai-services-resource-group

リファレンスのドキュメント | ライブラリのソース コード | パッケージ (NuGet) | サンプル

C# の前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• 最新バージョンの .NET Core。
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure サービス プリンシパルを作成する

アプリケーションが Azure アカウントと対話できるようにするには、アクセス許可を管理するための Azure サービス プリンシパルが必要です。 Azure サービス プリンシパルの作成に関するページの手順に従ってください。

サービス プリンシパルを作成すると、それにシークレット値、ID、およびアプリケーション ID が含まれていることがわかります。 後の手順のために、アプリケーション ID とシークレットを一時的な場所に保存します。

リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループをアカウントに用意する必要があります。 リソース グループがまだ存在しない場合は、先に進む前に、Azure portal で作成します。

新しい C# アプリケーションを作成する

新しい .NET Core アプリケーションを作成します。 コンソール ウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、azure-management-quickstart という名前で新しいコンソール アプリを作成します。 このコマンドにより、1 つのソース ファイル (program.cs) を使用する単純な "Hello World" C# プロジェクトが作成されます。

dotnet new console -n azure-management-quickstart

新しく作成されたアプリ フォルダーにディレクトリを変更します。 次を使用してアプリケーションをビルドできます。

dotnet build

ビルドの出力に警告やエラーが含まれないようにする必要があります。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

クライアント ライブラリをインストールする

次のコマンドを使用して、アプリケーション ディレクトリ内に .NET 用 Azure Management クライアント ライブラリをインストールします。

dotnet add package Azure.ResourceManager.CognitiveServices
dotnet add package Microsoft.Azure.Management.Fluent
dotnet add package Microsoft.Azure.Management.ResourceManager.Fluent

Visual Studio IDE を使用している場合、クライアント ライブラリは、ダウンロード可能な NuGet パッケージとして入手できます。

ライブラリをインポートする

program.cs を開き、ファイルの先頭に次の using ステートメントを追加します。

using System;
using Microsoft.Azure.Management.Fluent;
using Microsoft.Azure.Management.ResourceManager.Fluent;
using Microsoft.Azure.Management.ResourceManager.Fluent.Authentication;
using Microsoft.Azure.Management.CognitiveServices;
using Microsoft.Azure.Management.CognitiveServices.Models;

クライアントを認証する

program.cs のルートに以下のフィールドを追加し、作成したサービス プリンシパルと Azure アカウント情報を使用して値を指定します。

const string  service_principal_application_id = "PASTE_YOUR_SERVICE_PRINCIPAL_APPLICATION_ID_HERE";
const string  service_principal_secret = "PASTE_YOUR_SERVICE_PRINCIPAL_SECRET_HERE";

/* The ID of your Azure subscription. You can find this in the Azure Dashboard under Home > Subscriptions. */
const string  subscription_id = "PASTE_YOUR_SUBSCRIPTION_ID_HERE";

/* The Active Directory tenant ID. You can find this in the Azure Dashboard under Home > Azure Active Directory. */
const string  tenant_id = "PASTE_YOUR_TENANT_ID_HERE";

/* The name of the Azure resource group in which you want to create the resource.
You can find resource groups in the Azure Dashboard under Home > Resource groups. */
const string  resource_group_name = "PASTE_YOUR_RESOURCE_GROUP_NAME_HERE";

/* The name of the custom subdomain to use when you create the resource. This is optional.
For example, if you create a Bing Search v7 resource with the custom subdomain name 'my-search-resource',
your resource would have the endpoint https://my-search-resource.cognitiveservices.azure.com/.
Note not all Cognitive Services allow custom subdomain names. */
const string subdomain_name = "PASTE_YOUR_SUBDOMAIN_NAME_HERE";

次に、Main メソッドでこれらの値を使用して、CognitiveServicesManagementClient オブジェクトを構築します。 このオブジェクトは、すべての Azure 管理操作に必要です。

var service_principal_credentials = new ServicePrincipalLoginInformation ();
service_principal_credentials.ClientId = service_principal_application_id;
service_principal_credentials.ClientSecret = service_principal_secret;

var credentials = SdkContext.AzureCredentialsFactory.FromServicePrincipal(service_principal_application_id, service_principal_secret, tenant_id, AzureEnvironment.AzureGlobalCloud);
var client = new CognitiveServicesManagementClient(credentials);
client.SubscriptionId = subscription_id;

管理メソッドを呼び出す

Main メソッドに次のコードを追加して、使用可能なリソースの一覧表示、サンプル リソースの作成、所有しているリソースの一覧表示、およびサンプル リソースの削除を行います。 これらのメソッドは、以降の手順で定義します。

    // Uncomment to list all available resource kinds, SKUs, and locations for your Azure account:
    //list_available_kinds_skus_locations(client);

    // Create a resource with kind TextTranslation, F0 (free tier), location global.
    create_resource(client, "test_resource", "TextTranslation", "F0", "Global");

    // List all resources for your Azure account and resource group:
    list_resources(client);

    // Delete the resource.
    delete_resource(client, "test_resource");

    Console.WriteLine("Press any key to exit.");
    Console.ReadKey();

Azure AI サービス リソースを作成する (C#)

新しい Azure AI サービス リソースを作成してサブスクライブするには、Create メソッドを使用します。 このメソッドで、渡したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。 次のメソッドは、これらのすべてを引数として受け取り、リソースを作成します。

static void create_resource(CognitiveServicesManagementClient client, string resource_name, string kind, string account_tier, string location)
{
    Console.WriteLine("Creating resource: " + resource_name + "...");
    /* NOTE If you do not want to use a custom subdomain name, remove the customSubDomainName
    property from CognitiveServicesAccountProperties. */
    CognitiveServicesAccount parameters = 
        new CognitiveServicesAccount(null, null, kind, location, resource_name, new CognitiveServicesAccountProperties(customSubDomainName : subdomain_name), new Sku(account_tier));
    var result = client.Accounts.Create(resource_group_name, resource_name, parameters);
    Console.WriteLine("Resource created.");
    Console.WriteLine("ID: " + result.Id);
    Console.WriteLine("Kind: " + result.Kind);
    Console.WriteLine();
}

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの "種類" と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。 使用できるAzure AI サービスの "種類" のリストを確認するには、スクリプトで次のメソッドを呼び出します。

static void list_available_kinds_skus_locations(CognitiveServicesManagementClient client)
{

    Console.WriteLine("Available SKUs:");
    var result = client.ResourceSkus.List();
    Console.WriteLine("Kind\tSKU Name\tSKU Tier\tLocations");
    foreach (var x in result) {
        var locations = "";
        foreach (var region in x.Locations)
        {
            locations += region;
        }
        Console.WriteLine(x.Kind + "\t" + x.Name + "\t" + x.Tier + "\t" + locations);
    };
}

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

リソースを表示する

Azure アカウントのすべてのリソース (すべてのリソース グループにわたる) を表示するには、次のメソッドを使用します。

static void list_resources(CognitiveServicesManagementClient client)
{
    Console.WriteLine("Resources in resource group: " + resource_group_name);
    var result = client.Accounts.ListByResourceGroup(resource_group_name);
    foreach (var x in result)
    {
        Console.WriteLine("ID: " + x.Id);
        Console.WriteLine("Name: " + x.Name);
        Console.WriteLine("Type: " + x.Type);
        Console.WriteLine("Kind: " + x.Kind);
        Console.WriteLine();
    }
}

リソースの削除

次のメソッドは、特定のリソース グループから指定されたリソースを削除します。

static void delete_resource(CognitiveServicesManagementClient client, string resource_name)
{
    Console.WriteLine("Deleting resource: " + resource_name + "...");
    client.Accounts.Delete (resource_group_name, resource_name);

    Console.WriteLine("Resource deleted.");
    Console.WriteLine();
}

アプリケーションの実行

アプリケーション ディレクトリから dotnet run コマンドを使用してアプリケーションを実行します。

dotnet run

リファレンス ドキュメント | ライブラリのソース コード | パッケージ (Maven)

Java の前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• 最新バージョンの Java Development Kit(JDK)
• Gradle ビルド ツール、または別の依存関係マネージャー。
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure サービス プリンシパルを作成する

アプリケーションが Azure アカウントと対話できるようにするには、アクセス許可を管理するための Azure サービス プリンシパルが必要です。 Azure サービス プリンシパルの作成に関するページの手順に従ってください。

サービス プリンシパルを作成すると、それにシークレット値、ID、およびアプリケーション ID が含まれていることがわかります。 後の手順のために、アプリケーション ID とシークレットを一時的な場所に保存します。

リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループをアカウントに用意する必要があります。 リソース グループがまだ存在しない場合は、先に進む前に、Azure portal で作成します。

新しい Java アプリケーションを作成する

コンソール ウィンドウ (cmd、PowerShell、Bash など) で、ご利用のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir myapp && cd myapp

作業ディレクトリから gradle init コマンドを実行します。 このコマンドによって、Gradle 用の重要なビルド ファイルが作成されます。たとえば、実行時にアプリケーションを作成して構成するために使用される build.gradle.kts などです。

gradle init --type basic

DSL を選択するよう求められたら、Kotlin を選択します。

作業ディレクトリから、次のコマンドを実行します。

mkdir -p src/main/java

クライアント ライブラリをインストールする

このクイックスタートでは、Gradle 依存関係マネージャーを使用します。 クライアント ライブラリとその他の依存関係マネージャーの情報については、Maven Central Repository を参照してください。

プロジェクトの build.gradle.kts ファイルに、必要なプラグインと設定と共に、クライアント ライブラリを implementation ステートメントとして含めます。

plugins {
    java
    application
}
application {
    mainClass.set("FormRecognizer")
}
repositories {
    mavenCentral()
}
dependencies {
    implementation(group = "com.microsoft.azure", name = "azure-mgmt-cognitiveservices", version = "1.10.0-beta")
}

ライブラリをインポートする

新しい src/main/java フォルダーに移動し、Management.java という名前のファイルを作成します。 それを任意のエディターまたは IDE で開き、以下の import ステートメントを追加します。

import com.azure.core.management.*;
import com.azure.core.management.profile.*;
import com.azure.identity.*;
import com.azure.resourcemanager.cognitiveservices.*;
import com.azure.resourcemanager.cognitiveservices.implementation.*;
import com.azure.resourcemanager.cognitiveservices.models.*;

import java.io.*;
import java.lang.Object.*;
import java.util.*;
import java.net.*;

クライアントを認証する

Management.java にクラスを追加した後、次のフィールドと値をその中に追加します。 作成したサービス プリンシパルと他の Azure アカウント情報を使用して、値を指定します。

/*
Be sure to use the service pricipal application ID, not simply the ID. 
*/

private static String applicationId = "PASTE_YOUR_SERVICE_PRINCIPAL_APPLICATION_ID_HERE";
private static String applicationSecret = "PASTE_YOUR_SERVICE_PRINCIPAL_SECRET_HERE";

/* The ID of your Azure subscription. You can find this in the Azure Dashboard under Home > Subscriptions. */
private static String subscriptionId = "PASTE_YOUR_SUBSCRIPTION_ID_HERE";

/* The Active Directory tenant ID. You can find this in the Azure Dashboard under Home > Azure Active Directory. */
private static String tenantId = "PASTE_YOUR_TENANT_ID_HERE";

/* The name of the Azure resource group in which you want to create the resource.
You can find resource groups in the Azure Dashboard under Home > Resource groups. */
private static String resourceGroupName = "PASTE_YOUR_RESOURCE_GROUP_NAME_HERE";

/* The name of the custom subdomain to use when you create the resource. This is optional.
For example, if you create a Bing Search v7 resource with the custom subdomain name 'my-search-resource',
your resource would have the endpoint https://my-search-resource.cognitiveservices.azure.com/.
Note not all Cognitive Services allow custom subdomain names. */
private static String subDomainName = "PASTE_YOUR_SUBDOMAIN_NAME_HERE";

次に、main メソッドでこれらの値を使用して、CognitiveServicesManager オブジェクトを構築します。 このオブジェクトは、すべての Azure 管理操作に必要です。

/* For more information see:
https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/docs/AUTH.md
*/

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .clientId(applicationId)
    .clientSecret(applicationSecret)
    .tenantId(tenantId)
    .build();
AzureProfile profile = new AzureProfile(tenantId, subscriptionId, AzureEnvironment.AZURE);

CognitiveServicesManager client = CognitiveServicesManager.authenticate(credential, profile);

管理メソッドを呼び出す

Main メソッドに次のコードを追加して、使用可能なリソースの一覧表示、サンプル リソースの作成、所有しているリソースの一覧表示、およびサンプル リソースの削除を行います。 これらのメソッドは、以降の手順で定義します。

String resourceName = "test_resource";
String resourceKind = "TextTranslation";
String resourceSku = "F0";
Region resourceRegion = Region.US_WEST;

// Uncomment to list all available resource kinds, SKUs, and locations for your Azure account.
// list_available_kinds_skus_locations (client);

// Create a resource with kind Text Translation, SKU F0 (free tier), location US West.
String resourceId = create_resource (client, resourceName, resourceGroupName, resourceKind, resourceSku, resourceRegion);

// Uncomment this to list all resources for your Azure account.
// list_resources (client, resourceGroupName);

// Delete the resource.
delete_resource (client, resourceId);

/* NOTE: When you delete a resource, it is only soft-deleted. You must also purge it. Otherwise, if you try to create another
resource with the same name or custom subdomain, you will receive an error stating that such a resource already exists. */
purge_resource (client, resourceName, resourceGroupName, resourceRegion);

Azure AI サービス リソースを作成する (Java)

新しい Azure AI サービス リソースを作成してサブスクライブするには、create メソッドを使用します。 このメソッドで、渡したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。 次のメソッドは、これらのすべてを引数として受け取り、リソースを作成します。

public static String create_resource (CognitiveServicesManager client, String resourceName, String resourceGroupName, String resourceKind, String resourceSku, Region resourceRegion) {
    System.out.println ("Creating resource: " + resourceName + "...");

    /* NOTE: If you do not want to use a custom subdomain name, remove the withCustomSubDomainName
    setter from the AccountProperties object. */
    Account result = client.accounts().define(resourceName)
        .withExistingResourceGroup(resourceGroupName)
        // Note: Do not call withRegion() first, as it does not exist on the Blank interface returned by define().
        .withRegion(resourceRegion)
        .withKind(resourceKind)
        .withSku(new Sku().withName(resourceSku))
        .withProperties(new AccountProperties().withCustomSubDomainName(subDomainName))
        .create();

    System.out.println ("Resource created.");
    System.out.println ("ID: " + result.id());
    System.out.println ("Provisioning state: " + result.properties().provisioningState().toString());
    System.out.println ();

    return result.id();
}

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの "種類" と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。 使用できる Azure AI サービスの "種類" のリストを確認するには、次のメソッドを呼び出します。

public static void list_available_kinds_skus_locations (CognitiveServicesManager client) {
    System.out.println ("Available SKUs:");
    System.out.println("Kind\tSKU Name\tSKU Tier\tLocations");
    ResourceSkus skus = client.resourceSkus();
    for (ResourceSku sku : skus.list()) {
        String locations = String.join (",", sku.locations());
        System.out.println (sku.kind() + "\t" + sku.name() + "\t" + sku.tier() + "\t" + locations);
    }
}

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

リソースを表示する

Azure アカウントのすべてのリソース (すべてのリソース グループにわたる) を表示するには、次のメソッドを使用します。

public static void list_resources (CognitiveServicesManager client, String resourceGroupName) {
    System.out.println ("Resources in resource group: " + resourceGroupName);
    // Note Azure resources are also sometimes referred to as accounts.
    Accounts accounts = client.accounts();
    for (Account account : accounts.listByResourceGroup(resourceGroupName)) {
        System.out.println ("ID: " + account.id());
        System.out.println ("Kind: " + account.kind ());
        System.out.println ("SKU Name: " + account.sku().name());
        System.out.println ("Custom subdomain name: " + account.properties().customSubDomainName());
        System.out.println ();
    }
}

リソースの削除

次のメソッドは、特定のリソース グループから指定されたリソースを削除します。

public static void delete_resource (CognitiveServicesManager client, String resourceId) {
    System.out.println ("Deleting resource: " + resourceId + "...");
    client.accounts().deleteById (resourceId);
    System.out.println ("Resource deleted.");
    System.out.println ();
}

リファレンスのドキュメント | ライブラリのソース コード | パッケージ (npm) | サンプル

JavaScript の前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• 最新バージョンの Node.js
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure サービス プリンシパルを作成する

アプリケーションが Azure アカウントと対話できるようにするには、アクセス許可を管理するための Azure サービス プリンシパルが必要です。 Azure サービス プリンシパルの作成に関するページの手順に従ってください。

サービス プリンシパルを作成すると、それにシークレット値、ID、およびアプリケーション ID が含まれていることがわかります。 後の手順のために、アプリケーション ID とシークレットを一時的な場所に保存します。

リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループをアカウントに用意する必要があります。 リソース グループがまだ存在しない場合は、先に進む前に、Azure portal で作成します。

新しい Node.js アプリケーションを作成する

コンソール ウィンドウ (cmd、PowerShell、Bash など) で、ご利用のアプリ用に新しいディレクトリを作成し、そこに移動します。

mkdir myapp && cd myapp

init コマンドを実行し、package.json ファイルを使用して node アプリケーションを作成します。

 init

先に進む前に、index.js というファイルを作成します。

クライアント ライブラリをインストールする

次の NPM パッケージをインストールします。

npm install @azure/arm-cognitiveservices
npm install @azure/identity

アプリの package.json ファイルが依存関係によって更新されます。

ライブラリをインポートする

index.js スクリプトを開き、以下のライブラリをインポートします。

"use strict";

/* To run this sample, install the following modules.
 * npm install @azure/arm-cognitiveservices @azure/identity
 */
var Arm = require("@azure/arm-cognitiveservices");
var Identity = require("@azure/identity");

クライアントを認証する

スクリプトのルートに以下のフィールドを追加し、作成したサービス プリンシパルと Azure アカウント情報を使用して値を指定します。

const service_principal_application_id =
  "PASTE_YOUR_SERVICE_PRINCIPAL_APPLICATION_ID_HERE";
const service_principal_secret = "PASTE_YOUR_SERVICE_PRINCIPAL_SECRET_HERE";

/* The ID of your Azure subscription. You can find this in the Azure Dashboard under Home > Subscriptions. */
const subscription_id = "PASTE_YOUR_SUBSCRIPTION_ID_HERE";

/* The Active Directory tenant ID. You can find this in the Azure Dashboard under Home > Azure Active Directory. */
const tenant_id = "PASTE_YOUR_TENANT_ID_HERE";

/* The name of the Azure resource group in which you want to create the resource.
You can find resource groups in the Azure Dashboard under Home > Resource groups. */
const resource_group_name = "PASTE_YOUR_RESOURCE_GROUP_NAME_HERE";

/* The name of the custom subdomain to use when you create the resource. This is optional.
For example, if you create a Bing Search v7 resource with the custom subdomain name 'my-search-resource',
your resource would have the endpoint https://my-search-resource.cognitiveservices.azure.com/.
Note not all Cognitive Services allow custom subdomain names.
*/
const subdomain_name = "PASTE_YOUR_SUBDOMAIN_NAME_HERE";

次に、プログラムの主要な作業を処理するために、次の quickstart 関数を追加します。 最初のコード ブロックでは、前に入力した資格情報変数を使用して、CognitiveServicesManagementClient オブジェクトを構築します。 このオブジェクトは、すべての Azure 管理操作に必要です。

async function quickstart() {
  /* For more information see:
https://www.npmjs.com/package/@azure/arm-cognitiveservices/v/6.0.0
https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-a-service-principal-with-a-client-secret
*/
  const credentials = new Identity.ClientSecretCredential(
    tenant_id,
    service_principal_application_id,
    service_principal_secret
  );
  const client = new Arm.CognitiveServicesManagementClient(
    credentials,
    subscription_id
  );
  // Note Azure resources are also sometimes referred to as accounts.
  const accounts_client = client.accounts;
  const resource_skus_client = client.resourceSkus;
  const deleted_accounts_client = client.deletedAccounts;

管理関数を呼び出す

quickstart 関数の末尾に次のコードを追加して、使用可能なリソースの一覧表示、サンプル リソースの作成、所有しているリソースの一覧表示、およびサンプル リソースの削除を行います。 これらの関数は、以降の手順で定義します。

Azure AI サービス リソースを作成する (Node.js)

新しい Azure AI サービス リソースを作成してサブスクライブするには、Create 関数を使用します。 この関数で、渡したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。 次の関数は、これらのすべての引数を受け取り、リソースを作成します。

async function create_resource(
  client,
  resource_name,
  resource_kind,
  resource_sku,
  resource_region
) {
  console.log("Creating resource: " + resource_name + "...");
  /* NOTE If you do not want to use a custom subdomain name, remove the customSubDomainName
property from the properties object. */
  var parameters = {
    sku: { name: resource_sku },
    kind: resource_kind,
    location: resource_region,
    properties: { customSubDomainName: subdomain_name },
  };
  return client
    .beginCreateAndWait(resource_group_name, resource_name, parameters)
    .then((result) => {
      console.log("Resource created.");
      console.log();
      console.log("ID: " + result.id);
      console.log("Kind: " + result.kind);
      console.log();
    })
    .catch((err) => {
      console.log(err);
    });
}

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの "種類" と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。 次の関数は、使用可能な Azure AI サービスの "種類" をリストします。

async function list_available_kinds_skus_locations(client) {
  console.log("Available SKUs:");
  var result = client.list();
  console.log("Kind\tSKU Name\tSKU Tier\tLocations");
  for await (let item of result) {
    var locations = item.locations.join(",");
    console.log(item.kind + "\t" + item.name + "\t" + item.tier + "\t" + locations);
  }
}

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

リソースを表示する

Azure アカウントのすべてのリソース (すべてのリソース グループにわたる) を表示するには、次の関数を使用します。

async function list_resources(client) {
  console.log("Resources in resource group: " + resource_group_name);
  var result = client.listByResourceGroup(resource_group_name);
  for await (let item of result) {
    console.log(item);
    console.log();
  }
}

リソースの削除

次の関数は、特定のリソース グループから指定されたリソースを削除します。

async function delete_resource(client, resource_name) {
  console.log("Deleting resource: " + resource_name + "...");
  await client.beginDeleteAndWait(resource_group_name, resource_name);
  console.log("Resource deleted.");
  console.log();
}

アプリケーションの実行

スクリプトの末尾に以下のコードを追加して、エラー処理付きのメイン quickstart 関数を呼び出します。

try {
  quickstart();
} catch (error) {
  console.log(error);
}

次に、コンソール ウィンドウで node コマンドを使用して、アプリケーションを実行します。

node index.js

リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PyPi) | サンプル

Python の前提条件

• 有効な Azure サブスクリプション - 無料アカウントを作成する。
• Python 3.x
• 責任ある AI のご契約条件に同意してリソースを作成するためには、Azure アカウントに Cognitive Services Contributor ロールが割り当てられている必要があります。 このロールをアカウントに割り当てるには、ロールの割り当てに関するドキュメントの手順に従うか、管理者にお問い合わせください。
• Azure AI Vision で空間分析を、または Azure AI Language で Text Analytics for Health を使用する計画がある場合は、ご契約条件を確認して承認できるように、Azure portal で最初の Vision リソースまたは Language リソースを作成する必要があります。 これは、それぞれ Azure AI Language、Azure AI Vision のリンクから行うことができます。 その後、同じ Azure サブスクリプションの下で任意のデプロイ ツール (SDK、CLI、または ARM テンプレートなど) を使用して、後続のリソースを作成できます。

Azure サービス プリンシパルを作成する

アプリケーションが Azure アカウントと対話できるようにするには、アクセス許可を管理するための Azure サービス プリンシパルが必要です。 Azure サービス プリンシパルの作成に関するページの手順に従ってください。

サービス プリンシパルを作成すると、それにシークレット値、ID、およびアプリケーション ID が含まれていることがわかります。 後の手順のために、アプリケーション ID とシークレットを一時的な場所に保存します。

リソース グループを作成する

Azure AI サービス リソースを作成する前に、リソースを格納するための Azure リソース グループをアカウントに用意する必要があります。 リソース グループがまだ存在しない場合は、先に進む前に、Azure portal で作成します。

新しい Python アプリケーションを作成する

お気に入りのエディターまたは IDE で新しい Python アプリケーションを作成し、コンソール ウィンドウでプロジェクトに移動します。

クライアント ライブラリをインストールする

次のようにして、クライアント ライブラリをインストールできます。

pip install azure-mgmt-cognitiveservices

また、Microsoft Entra トークン認証のサポート用に Azure ID ライブラリもインストールしてください。

pip install azure-identity

ライブラリをインポートする

Python スクリプトを開き、以下のライブラリをインポートします。

import time
from azure.identity import ClientSecretCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from azure.mgmt.cognitiveservices.models import Account, Sku

クライアントを認証する

スクリプトのルートに以下のフィールドを追加し、作成したサービス プリンシパルと Azure アカウント情報を使用して値を指定します。

# Be sure to use the service pricipal application ID, not simply the ID. 
service_principal_application_id = "PASTE_YOUR_SERVICE_PRINCIPAL_APPLICATION_ID_HERE"
service_principal_secret = "PASTE_YOUR_SERVICE_PRINCIPAL_SECRET_HERE"

# The ID of your Azure subscription. You can find this in the Azure Dashboard under Home > Subscriptions.
subscription_id = "PASTE_YOUR_SUBSCRIPTION_ID_HERE"

# The Active Directory tenant ID. You can find this in the Azure Dashboard under Home > Azure Active Directory.
tenant_id = "PASTE_YOUR_TENANT_ID_HERE"

# The name of the Azure resource group in which you want to create the resource.
# You can find resource groups in the Azure Dashboard under Home > Resource groups.
resource_group_name = "PASTE_YOUR_RESOURCE_GROUP_NAME_HERE"

# The name of the custom subdomain to use when you create the resource. This is optional.
# For example, if you create a Bing Search v7 resource with the custom subdomain name 'my-search-resource',
# your resource would have the endpoint https://my-search-resource.cognitiveservices.azure.com/.
# Note not all Cognitive Services allow custom subdomain names.
subdomain_name = "PASTE_YOUR_SUBDOMAIN_NAME_HERE"

# How many seconds to wait between checking the status of an async operation.
wait_time = 10

次に、次のコードを追加して、CognitiveServicesManagementClient オブジェクトを構築します。 このオブジェクトは、すべての Azure 管理操作に必要です。

credential = ClientSecretCredential(tenant_id, service_principal_application_id, service_principal_secret)
client = CognitiveServicesManagementClient(credential, subscription_id)

Azure AI サービス リソースを作成する (Python)

新しい Azure AI サービス リソースを作成してサブスクライブするには、Create 関数を使用します。 この関数で、渡したリソース グループに新しい課金対象リソースが追加されます。 新しいリソースを作成するときには、使用するサービスの "種類"、その価格レベル (つまり SKU)、および Azure の場所を把握している必要があります。 次の関数は、これらのすべての引数を受け取り、リソースを作成します。

def create_resource (resource_name, kind, sku_name, location) :
    print("Creating resource: " + resource_name + "...")

# NOTE If you do not want to use a custom subdomain name, remove the customSubDomainName
# property from the properties object.
    parameters = Account(sku=Sku(name=sku_name), kind=kind, location=location, properties={ 'custom_sub_domain_name' : subdomain_name })

    poller = client.accounts.begin_create(resource_group_name, resource_name, parameters)
    while (False == poller.done ()) :
        print ("Waiting {wait_time} seconds for operation to finish.".format (wait_time = wait_time))
        time.sleep (wait_time)
# This will raise an exception if the server responded with an error.
    result = poller.result ()

    print("Resource created.")
    print()
    print("ID: " + result.id)
    print("Name: " + result.name)
    print("Type: " + result.type)
    print()

サービスと価格レベルを選択する

新しいリソースを作成するときには、使用するサービスの "種類" と、必要な価格レベル (つまり SKU) を把握する必要があります。 リソースを作成するときに、この情報と他の情報をパラメーターとして使用します。 次の関数は、使用可能な Azure AI サービスの "種類" をリストします。

def list_available_kinds_skus_locations():
    print("Available SKUs:")
    result = client.resource_skus.list()
    print("Kind\tSKU Name\tSKU Tier\tLocations")
    for x in result:
        locations = ",".join(x.locations)
        print(x.kind + "\t" + x.name + "\t" + x.tier + "\t" + locations)

次の表に、Azure AI サービスの製品と価格に関する情報を示します。

マルチサービス

サービス	種類
複数のサービス。 詳細については、価格に関するページを参照してください。	CognitiveServices

視覚

サービス	種類
Vision	ComputerVision
Custom Vision - Prediction	CustomVision.Prediction
Custom Vision - Training	CustomVision.Training
Face	Face
Document Intelligence	FormRecognizer

音声

サービス	種類
Speech	SpeechServices

Language

サービス	種類
Language Understanding (LUIS)	LUIS
QnA Maker	QnAMaker
Language	TextAnalytics
Text Translation	TextTranslation

決定

サービス	種類
Anomaly Detector	AnomalyDetector
Content Moderator	ContentModerator
Personalizer	Personalizer

Azure OpenAI

サービス	種類
Azure OpenAI	OpenAI

価格レベルと請求

価格レベル (および請求される金額) は、認証情報を使用して送信するトランザクションの数に基づきます。 各価格レベルにより、以下が指定されます。

• 1 秒あたりに許可されるトランザクションの最大数 (TPS)。
• 価格レベル内で有効にされるサービス機能。
• 事前に定義された数のトランザクションのコスト。 この数を超えると、サービスの「価格の詳細」で指定されている追加料金が発生します。

Note

Azure AI サービスの多くには無料レベルがあり、これを使用してサービスを試すことができます。 無料レベルを使用するには、リソースの価格レベルとして F0 を使用します。

リソースを表示する

Azure アカウントのすべてのリソース (すべてのリソース グループにわたる) を表示するには、次の関数を使用します。

def list_resources():
    print("Resources in resource group: " + resource_group_name)
    result = client.accounts.list_by_resource_group(resource_group_name)
    for x in result:
        print(x.name)
        print(x)
        print()

リソースの削除

次の関数は、特定のリソース グループから指定されたリソースを削除します。

def delete_resource(resource_name) :
    print("Deleting resource: " + resource_name + "...")

    poller = client.accounts.begin_delete(resource_group_name, resource_name)
    while (False == poller.done ()) :
        print ("Waiting {wait_time} seconds for operation to finish.".format (wait_time = wait_time))
        time.sleep (wait_time)
# This will raise an exception if the server responded with an error.
    result = poller.result ()

    print("Resource deleted.")

管理関数を呼び出す

以下のコードをスクリプトの末尾に追加して、上の関数を呼び出します。 このコードは、使用可能なリソースの一覧表示、サンプル リソースの作成、所有しているリソースの一覧表示、およびサンプル リソースの削除を行います。

resource_name = "test_resource"
resource_kind = "TextTranslation"
resource_sku = "F0"
resource_location = "Global"

# Uncomment this to list all available resource kinds, SKUs, and locations for your Azure account.
#list_available_kinds_skus_locations ()

# Create a resource with kind Text Translation, SKU F0 (free tier), location global.
create_resource(resource_name, resource_kind, resource_sku, resource_location)

# Uncomment this to list all resources for your Azure account.
#list_resources()

# Delete the resource.
delete_resource(resource_name)

# NOTE: Deleting a resource only soft-deletes it. To delete it permanently, you must purge it.
# Otherwise, if you later try to create a resource with the same name, you will receive the following error:
# azure.core.exceptions.ResourceExistsError: (FlagMustBeSetForRestore) An existing resource with ID '<your resource ID>' has been soft-deleted. To restore the resource, you must specify 'restore' to be 'true' in the property. If you don't want to restore existing resource, please purge it first.
# Code: FlagMustBeSetForRestore

# Purge the resource.
purge_resource(resource_name, resource_location)

アプリケーションの実行

コマンド ラインで python コマンドを使用して、アプリケーションを実行します。

python <your-script-name>.py

次のステップ

• リソースが用意できたので、サポートされている Azure AI サービスのいずれかに対する API 要求を認証できます。