オーケストレーション ワークフローでプロジェクトを作成する方法

オーケストレーション ワークフローを使用すると、アプリケーションを次の機能に接続するプロジェクトを作成できます。

• カスタム言語理解
• 質問の回答
• LUIS

前提条件

オーケストレーション ワークフローの使用を開始する前に、必要なものがいくつかあります。

• Azure サブスクリプション - 無料で作成できます。
• Azure AI Language リソース

言語リソースを作成

オーケストレーション ワークフローの使用を開始する前に、Azure AI Language リソースが必要になります。

Note

• 言語リソースを作成するには、リソース グループに所有者ロールが割り当てられている必要があります。
• 質問応答を使用する予定の場合は、リソースの作成で質問応答を有効にする必要があります

Azure portal から新しいリソースを作成します

1. Azure portal に移動し、新しい Azure AI Language リソースを作成します。

2. [リソースの作成を続行する] を選択します

3. 次の詳細を使用して言語リソースを作成します。

   インスタンスの詳細	必須値
   リージョン	サポートされているリージョンのいずれか。
   名前	Language リソースの名前。
   Pricing tier	サポートされている価格レベルのいずれか。

Language Studio から新しい言語リソースを作成する

初めてログインするときは、既存の言語リソースを選択したり、新規に作成したりできるようにするウィンドウが Language Studio に表示されます。 また、右上隅にある設定アイコンをクリックし、 [リソース] を選び、 [新しいリソースを作成する] をクリックしてリソースを作成することもできます。

次の詳細を使用して言語リソースを作成します。

インスタンスの詳細	必須値
Azure サブスクリプション	お使いの Azure サブスクリプション
Azure リソース グループ	Azure リソース グループ
Azure リソース名	Azure リソース名
場所	サポートされているリージョンに関する詳細情報。
価格レベル	サポートされる価格レベルに関する詳細情報。

重要

• Language リソースを作成する際は、必ず [マネージド ID] を有効にしてください。
• 責任ある AI 通知を読んで確認する

Language Studio にサインインする

新しい意図を作成するには、[+ 追加] ボタンを選択し、まず意図に名前を付けます。 プロジェクトに接続するか接続しないかの 2 つのオプションが表示されます。 プロジェクト (LUIS、質問応答、会話言語理解) に接続することも、[いいえ] オプションを選択することもできます。

オーケストレーション ワークフロー プロジェクトを作成する

言語リソースを作成したら、オーケストレーション ワークフロー プロジェクトを作成します。

Language Studio

1. Language Studio で [質問と会話言語を理解する] というラベルのセクションを見つけて、[オーケストレーション ワークフロー] を選択します。

   

2. これにより、オーケストレーション ワークフロー プロジェクト ページに移動します。 [新しいプロジェクトの作成] を選択します。 プロジェクトを作成するには、次の詳細を指定する必要があります。

値	内容
名前	プロジェクトの名前。
説明	オプションのプロジェクトの説明。
発話の主要言語	プロジェクトの第一言語。 トレーニング データは、主にこの言語にする必要があります。

完了したら、[次へ] を選択し、詳細を確認します。 [プロジェクトの作成] を選択してプロセスを完了します。 プロジェクトの [Build Schema](スキーマのビルド) 画面が表示されます。

REST API

新しいプロジェクトを作成するには、次の URL、ヘッダー、JSON 本文を使って PATCH 要求を送信します。

要求 URL

API 要求を作るときは、次の URL を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出す API のバージョン。	2023-04-01

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

Body

次のサンプル JSON を本文として使います。

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

Key	プレースホルダー	値	例
projectName	{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	EmailApp
language	{LANGUAGE-CODE}	プロジェクトで使用される発話の言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどの発話の言語コードを選択します。	en-us

オーケストレーション ワークフロー プロジェクトをインポートする

Language Studio

オーケストレーション ワークフロー プロジェクトのページに移動してプロジェクトを選択し、上部のメニューで [エクスポート] をクリックすれば、いつでもオーケストレーション ワークフロー プロジェクトを JSON ファイルとしてエクスポートできます。

そのプロジェクトを新しいプロジェクトとしてインポートし直すことができます。 まったく同じ名前でプロジェクトをインポートすると、プロジェクトのデータが新しくインポートしたプロジェクトのデータに置き換えられます。

プロジェクトをインポートするには、[新しいプロジェクトの作成] の横にある矢印ボタンを選択し、[インポート] を選択してから、JSON ファイルを選択します。

REST API

オーケストレーション ワークフローの JSON を、サービスにインポートできます

プロジェクトをインポートするには、次の URL、ヘッダー、JSON 本文を使って POST 要求を送信します。

要求 URL

API 要求を作るときは、次の URL を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出す API のバージョン。	2023-04-01

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

Body

注意

各意図は、(CLU、LUIS、qna) から 1 つの種類のみにする必要があります

次のサンプル JSON を本文として使います。

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00000000-0000-0000-0000-000000000000",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

Key	プレースホルダー	値	例
api-version	{API-VERSION}	呼び出している API のバージョン。 ここで使用するバージョンは、URL 内と同じ API バージョンである必要があります。	2022-03-01-preview
projectName	{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	EmailApp
language	{LANGUAGE-CODE}	プロジェクトで使用される発話の言語コードを指定する文字列。 プロジェクトが多言語プロジェクトの場合は、ほとんどの発話の言語コードを選択します。	en-us

プロジェクトをエクスポートする

Language Studio

オーケストレーション ワークフロー プロジェクトのページに移動し、プロジェクトを選択して、[エクスポート] をクリックすることで、いつでもオーケストレーション ワークフロー プロジェクトを JSON ファイルとしてエクスポートできます。

REST API

オーケストレーション ワークフロー プロジェクトは、いつでも JSON ファイルとしてエクスポートできます。

プロジェクトをエクスポートするには、次の URL、ヘッダー、JSON 本文を使って POST 要求を作成します。

要求 URL

API 要求を作るときは、次の URL を使います。 次のプレースホルダーの値を実際の値に置き換えてください。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	EmailApp
{API-VERSION}	呼び出す API のバージョン。	2023-04-01

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

API 要求を送信すると、成功を示す 202 応答が返されます。 応答ヘッダーで、operation-location の値を抽出します。 それは次のように書式設定されています。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

この操作は非同期であるため、JOB-ID を使って要求が識別されます。 同じ認証方法を使用し、エクスポートされたプロジェクトの JSON をこの URL を使用して取得します。

オーケストレーション プロジェクトの詳細を取得する

Language Studio

1. Language Studio でプロジェクト設定のページに移動します。

2. プロジェクトの詳細を確認できます。

3. このページでは、プロジェクトの説明を更新できます。

4. このページからリソースの主キーを取得することもできます。

   

REST API

オーケストレーション ワークフロー プロジェクトの詳細を取得するには、次の URL とヘッダーを使用して GET 要求を送信します。 プレースホルダーの値は、実際の値に置き換えます。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出す API のバージョン。	2023-04-01

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

応答本文

要求を送信すると、次の応答を受け取ります。

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Orchestration",
  "projectName": "{PROJECT-NAME}",
  "description": "This is a sample orchestration project.",
  "language": "{LANGUAGE-CODE}"
}

API 要求を送信すると、成功を示す 200 応答とプロジェクトの詳細を含む JSON 応答本文が返されます。

プロジェクトの削除

Language Studio

プロジェクトが不要な場合は、Language Studio を使ってプロジェクトを削除できます。 左側のナビゲーション メニューで [プロジェクト] を選択し、削除するプロジェクトを選択して、上部のメニューで [削除] を選択します。

REST API

プロジェクトが不要になったら、API を使用してプロジェクトを削除できます。

会話言語理解プロジェクトを削除するには、次の URL、ヘッダー、JSON 本文を使って DELETE 要求を作成します。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

プレースホルダー	値	例
{ENDPOINT}	API 要求を認証するためのエンドポイント。	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	プロジェクトの名前。 この値は、大文字と小文字が区別されます。	myProject
{API-VERSION}	呼び出す API のバージョン。	2023-04-01

ヘッダー

要求を認証するには、次のヘッダーを使います。

Key	値
Ocp-Apim-Subscription-Key	リソースへのキー。 API 要求の認証に使われます。

API 要求を送信すると、成功を示す 202 応答を受け取ります。これは、プロジェクトが削除されたことを意味します。

次の手順

スキーマの作成