オーサリング API

  • [アーティクル]

カスタム質問応答の Authoring API を使用して、新しい質問応答ペアの追加や、プロジェクトの作成、発行、管理などの一般的なタスクを自動化します。

Note

オーサリング機能は REST API とオーサリング SDK (プレビュー) を使用して使用できます。 この記事では、cURL と REST API を使用する例を示します。 利用可能なすべてのパラメーターと機能に関する完全なドキュメントについては、REST API リファレンス コンテンツを参照してください。

前提条件

  • 最新バージョンの cURL。 この記事では、いくつかのコマンド ライン スイッチが使用されています。これらのスイッチについては、cURL のドキュメントを参照してください。
  • この記事のコマンドは、Bash シェルで実行するように設計されています。 これらのコマンドは、変更せずに Windows コマンド プロンプトまたは PowerShell で常に動作するとは限りません。 Bash シェルがローカルにインストールされていない場合は、Azure Cloud Shell の bash 環境を使用できます。

プロジェクトを作成する

プロジェクトをプログラムで作成するには:

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[予測 URL の取得] で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 前の例が、次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[予測 URL の取得] で値を見つけることができます。 キー値は、サンプル要求の一部です。
NEW-PROJECT-NAME 新しいカスタム質問応答プロジェクトの名前。

また、プロジェクトの言語、信頼度のしきい値以上の応答が見つからない場合の既定の応答、およびこの言語リソースが複数の言語をサポートするかどうかなどの追加の値を調整することもできます。

クエリの例

curl -X PATCH -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '{
      "description": "proj1 is a test project.",
      "language": "en",
      "settings": {
        "defaultAnswer": "No good match found for your question in the project."
      },
      "multilingualResource": true
    }
  }'  'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{NEW-PROJECT-NAME}?api-version=2021-10-01'

応答の例

{
 "200": {
      "headers": {},
      "body": {
        "projectName": "proj1",
        "description": "proj1 is a test project.",
        "language": "en",
        "settings": {
          "defaultAnswer": "No good match found for your question in the project."
        },
        "multilingualResource": true,
        "createdDateTime": "2021-05-01T15:13:22Z",
        "lastModifiedDateTime": "2021-05-01T15:13:22Z",
        "lastDeployedDateTime": "2021-05-01T15:13:22Z"
      }
 }
}

プロジェクトを削除します。

プロジェクトをプログラムで削除するには:

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 前の例が、次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME 削除するプロジェクトの名前。

クエリの例

curl -X DELETE -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}?api-version=2021-10-01'

プロジェクトの削除を正常に呼び出した結果、Operation-Location ヘッダーが返されます。これを使用して、プロジェクトの削除ジョブの状態を確認できます。 ほとんどの例では、応答ヘッダーを確認する必要がないため、表示されていません。 応答ヘッダーを取得するには、curl コマンドで -i を使用します。 エンドポイント アドレスの前にこのパラメーターがないと、このコマンドに対する応答は、応答が発生しなかった場合と同様に空のままになります。

応答の例

HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/deletion-jobs/{JOB-ID-GUID}
x-envoy-upstream-service-time: 324
apim-request-id:
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Tue, 23 Nov 2021 20:56:18 GMT

プロジェクトが既に削除されている場合、または見つからなかった場合は、次のようなメッセージが表示されます。

{
  "error": {
    "code": "ProjectNotFound",
    "message": "The specified project was not found.",
    "details": [
      {
        "code": "ProjectNotFound",
        "message": "{GUID}"
      }
    ]
  }
}

プロジェクトの削除状態を取得する

プロジェクトの削除要求の状態を確認するには、次のようにします。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[予測 URL の取得] で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME デプロイ状態を確認するプロジェクトの名前。
JOB-ID プロジェクトをプログラムで削除すると、削除要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/deletion-jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/deletion-jobs/{JOB-ID}?api-version=2021-10-01'

応答の例

{
  "createdDateTime": "2021-11-23T20:56:18+00:00",
  "expirationDateTime": "2021-11-24T02:56:18+00:00",
  "jobId": "GUID",
  "lastUpdatedDateTime": "2021-11-23T20:56:18+00:00",
  "status": "succeeded"
}

プロジェクト設定を取得する

指定されたプロジェクトに関する情報を取得するには、次のクエリの値を更新します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME 情報を取得するプロジェクトの名前。

クエリの例


curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}?api-version=2021-10-01'

応答の例

 {
    "200": {
      "headers": {},
      "body": {
        "projectName": "proj1",
        "description": "proj1 is a test project.",
        "language": "en",
        "settings": {
          "defaultAnswer": "No good match found for your question in the project."
        },
        "createdDateTime": "2021-05-01T15:13:22Z",
        "lastModifiedDateTime": "2021-05-01T15:13:22Z",
        "lastDeployedDateTime": "2021-05-01T15:13:22Z"
      }
    }
  }

質問応答ペアを取得する

特定のプロジェクトに関する質問応答ペアと関連情報を取得するには、次のクエリの値を更新します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME すべての質問応答のペアを取得するプロジェクトの名前。

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/qnas?api-version=2021-10-01'

応答の例

{
    "200": {
      "headers": {},
      "body": {
        "value": [
          {
            "id": 1,
            "answer": "ans1",
            "source": "source1",
            "questions": [
              "question 1.1",
              "question 1.2"
            ],
            "metadata": {
              "k1": "v1",
              "k2": "v2"
            },
            "dialog": {
              "isContextOnly": false,
              "prompts": [
                {
                  "displayOrder": 1,
                  "qnaId": 11,
                  "displayText": "prompt 1.1"
                },
                {
                  "displayOrder": 2,
                  "qnaId": 21,
                  "displayText": "prompt 1.2"
                }
              ]
            },
            "lastUpdatedDateTime": "2021-05-01T17:21:14Z"
          },
          {
            "id": 2,
            "answer": "ans2",
            "source": "source2",
            "questions": [
              "question 2.1",
              "question 2.2"
            ],
            "lastUpdatedDateTime": "2021-05-01T17:21:14Z"
          }
        ]
      }
    }
  }

ソースを取得する

特定のプロジェクトに関するソースと関連情報を取得するには、次のクエリの値を更新します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME すべてのソース情報を取得するプロジェクトの名前。

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT_NAME}/sources?api-version=2021-10-01'

応答の例

{
    "200": {
      "headers": {},
      "body": {
        "value": [
          {
            "displayName": "source1",
            "sourceUri": "https://learn.microsoft.com/azure/ai-services/qnamaker/overview/overview",
            "sourceKind": "url",
            "lastUpdatedDateTime": "2021-05-01T15:13:22Z"
          },
          {
            "displayName": "source2",
            "sourceUri": "https://download.microsoft.com/download/2/9/B/29B20383-302C-4517-A006-B0186F04BE28/surface-pro-4-user-guide-EN.pdf",
            "sourceKind": "file",
            "contentStructureKind": "unstructured",
            "lastUpdatedDateTime": "2021-05-01T15:13:22Z"
          }
        ]
      }
    }
  }

シノニムを取得する

特定のプロジェクトに関するシノニムと関連情報を取得するには、次のクエリの値を更新します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME シノニム情報を取得するプロジェクトの名前。

クエリの例


curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/synonyms?api-version=2021-10-01'

応答の例

 {
    "200": {
      "headers": {},
      "body": {
        "value": [
          {
            "alterations": [
              "qnamaker",
              "qna maker"
            ]
          },
          {
            "alterations": [
              "botframework",
              "bot framework"
            ]
          }
        ]
      }
    }
  }

プロジェクトの配置

プロジェクトを運用環境にデプロイするには、次のクエリの値を更新します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME 運用環境にデプロイするプロジェクトの名前。

クエリの例

curl -X PUT -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/deployments/production?api-version=2021-10-01'

プロジェクトの配置を正常に呼び出した結果、Operation-Location ヘッダーが返されます。これを使用して、配置ジョブの状態を確認できます。 ほとんどの例では、応答ヘッダーを確認する必要がないため、表示されていません。 応答ヘッダーを取得するには、curl コマンドで -i を使用します。 エンドポイント アドレスの前にこのパラメーターがないと、このコマンドに対する応答は、応答が発生しなかった場合と同様に空のままになります。

応答の例

0HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/deployments/production/jobs/{JOB-ID-GUID}
x-envoy-upstream-service-time: 31
apim-request-id:
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Tue, 23 Nov 2021 20:35:00 GMT

プロジェクトの配置状態を取得する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME デプロイ状態を確認するプロジェクトの名前。
JOB-ID プロジェクトをプログラムによってデプロイすると、デプロイ要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/deployments/production/jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/deployments/production/jobs/{JOB-ID}?api-version=2021-10-01'

応答の例

    {
    "200": {
      "headers": {},
      "body": {
        "errors": [],
        "createdDateTime": "2021-05-01T17:21:14Z",
        "expirationDateTime": "2021-05-01T17:21:14Z",
        "jobId": "{JOB-ID-GUID}",
        "lastUpdatedDateTime": "2021-05-01T17:21:14Z",
        "status": "succeeded"
      }
    }
  }

プロジェクトのメタデータとアセットをエクスポートする

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME エクスポートするプロジェクトの名前。

クエリの例

curl -X POST -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '{exportAssetTypes": ["qnas","synonyms"]}' -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/:export?api-version=2021-10-01&format=tsv'

応答の例

HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/Sample-project/export/jobs/{JOB-ID_GUID}
x-envoy-upstream-service-time: 214
apim-request-id:
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Tue, 23 Nov 2021 21:24:03 GMT

エクスポート状態を確認する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME エクスポート状態を確認するプロジェクトの名前。
JOB-ID プロジェクトをプログラムでエクスポートすると、エクスポート要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/sample-proj1/export/jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/sample-proj1/export/jobs/{JOB-ID}?api-version=2021-10-01'

応答の例

{
  "createdDateTime": "2021-11-23T21:24:03+00:00",
  "expirationDateTime": "2021-11-24T03:24:03+00:00",
  "jobId": "JOB-ID-GUID",
  "lastUpdatedDateTime": "2021-11-23T21:24:08+00:00",
  "status": "succeeded",
  "resultUrl": "https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/export/jobs/{JOB-ID_GUID}/result"
}

resultUrl に直接アクセスしようとすると、404 エラーが発生します。 認証された要求によってアクセスできるようにするには、パスに ?api-version=2021-10-01 を追加する必要があります。https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/export/jobs/{JOB-ID_GUID}/result?api-version=2021-10-01

プロジェクトのインポート

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME インポート先として使用するプロジェクトの名前。
FILE-URI-PATH プロジェクトをプログラムでエクスポートし、エクスポートの状態を確認すると、応答の一部として resultUrl が生成されます。 たとえば、次のようになります。"resultUrl": "https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/export/jobs/{JOB-ID_GUID}/result"。resultUrl に API バージョンを追加して、プロジェクトをインポートするソース ファイルとして使用できますhttps://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/export/jobs/{JOB-ID_GUID}/result?api-version=2021-10-01。

クエリの例

curl -X POST -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '{
      "fileUri": "FILE-URI-PATH"
  }' -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/:import?api-version=2021-10-01&format=tsv'

プロジェクトのインポートを正常に呼び出した結果、Operation-Location ヘッダーが返されます。これを使用して、インポート ジョブの状態を確認できます。 多くの例では、応答ヘッダーを確認する必要がないため、表示されていません。 応答ヘッダーを取得するには、curl コマンドで -i を使用します。 エンドポイント アドレスの前にこの追加パラメーターがないと、このコマンドに対する応答は、応答が発生しなかった場合と同様に空のままになります。

応答の例

HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/sample-proj1/import/jobs/{JOB-ID-GUID}
x-envoy-upstream-service-time: 417
apim-request-id: 
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Wed, 24 Nov 2021 00:35:11 GMT

インポートの状態を確認する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME インポート先として使用するプロジェクトの名前。
JOB-ID プロジェクトをプログラムでインポートすると、エクスポート要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/sample-proj1/import/jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME/import/jobs/{JOB-ID-GUID}?api-version=2021-10-01'

クエリ応答の例

{
  "errors": [],
  "createdDateTime": "2021-05-01T17:21:14Z",
  "expirationDateTime": "2021-05-01T17:21:14Z",
  "jobId": "JOB-ID-GUID",
  "lastUpdatedDateTime": "2021-05-01T17:21:14Z",
  "status": "succeeded"
}

List deployments

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME デプロイ リストを生成するプロジェクトの名前。

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/deployments?api-version=2021-10-01'

応答の例

[
  {
    "deploymentName": "production",
    "lastDeployedDateTime": "2021-10-26T15:12:02Z"
  }
]

プロジェクトの一覧表示

アカウントがアクセス権を持つすべての質問応答プロジェクトの一覧を取得します。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects?api-version=2021-10-01'

応答の例

{
  "value": [
    {
      "projectName": "Sample-project",
      "description": "My first question answering project",
      "language": "en",
      "multilingualResource": false,
      "createdDateTime": "2021-10-07T04:51:15Z",
      "lastModifiedDateTime": "2021-10-27T00:42:01Z",
      "lastDeployedDateTime": "2021-11-24T01:34:18Z",
      "settings": {
        "defaultAnswer": "No good match found in KB"
      }
    }
  ]
}

ソースを更新する

この例では、既存のプロジェクトに新しいソースを追加します。 クエリ本文の一部として渡す操作の種類に応じて、このコマンドで既存のソースを置換および削除することもできます。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME ソースを更新するプロジェクトの名前。
METHOD PATCH

クエリの例

curl -X PATCH -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '[
  {
    "op": "add",
    "value": {
      "displayName": "source5",
      "sourceKind": "url",
      "sourceUri": "https://download.microsoft.com/download/7/B/1/7B10C82E-F520-4080-8516-5CF0D803EEE0/surface-book-user-guide-EN.pdf",
      "sourceContentStructureKind": "semistructured"
    }
  }
]'  -i '{LanguageServiceName}.cognitiveservices.azure.com//language/query-knowledgebases/projects/{projectName}/sources?api-version=2021-10-01'

ソースの更新を正常に呼び出した結果、Operation-Location ヘッダーが返されます。これを使用して、インポート ジョブの状態を確認できます。 多くの例では、応答ヘッダーを確認する必要がないため、常に表示されていません。 応答ヘッダーを取得するには、curl コマンドで -i を使用します。 エンドポイント アドレスの前にこのパラメーターがないと、このコマンドに対する応答は、応答が発生しなかった場合と同様に空のままになります。

応答の例

HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/Sample-project/sources/jobs/{JOB_ID_GUID}
x-envoy-upstream-service-time: 412
apim-request-id: dda23d2b-f110-4645-8bce-1a6f8d504b33
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Wed, 24 Nov 2021 02:47:53 GMT

ソースの更新状態を取得する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[予測 URL の取得] で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME インポート先として使用するプロジェクトの名前。
JOB-ID ソースをプログラムによって更新すると、ソースの更新要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/sample-proj1/sources/jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/sources/jobs/{JOB-ID}?api-version=2021-10-01'

応答の例

{
  "createdDateTime": "2021-11-24T02:47:53+00:00",
  "expirationDateTime": "2021-11-24T08:47:53+00:00",
  "jobId": "{JOB-ID-GUID}",
  "lastUpdatedDateTime": "2021-11-24T02:47:56+00:00",
  "status": "succeeded",
  "resultUrl": "/knowledgebases/Sample-project"
}

質問応答ペアを更新する

この例では、既存のソースに質問応答ペアを追加します。 また、クエリ本文で渡す操作に応じて、このクエリを使用して既存の質問応答ペアを変更または削除することもできます。 source5 という名前のソースがない場合、このクエリの例は失敗します。 クエリの本文のソース値を、ターゲット プロジェクトについて存在するソースと調整できます。

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME インポート先として使用するプロジェクトの名前。 
curl -X PATCH -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '[
    {
        "op": "add",
        "value":{
            "id": 1,
            "answer": "The latest question answering docs are on https://learn.microsoft.com",
            "source": "source5",
            "questions": [
                "Where do I find docs for question answering?"
            ],
            "metadata": {},
            "dialog": {
                "isContextOnly": false,
                "prompts": []
            }
        }
    }
]'  -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/qnas?api-version=2021-10-01'

質問応答ペアの更新を正常に呼び出した結果、Operation-Location ヘッダーが返されます。これを使用して、更新ジョブの状態を確認できます。 多くの例では、応答ヘッダーを確認する必要がないため、常に表示されていません。 応答ヘッダーを取得するには、curl コマンドで -i を使用します。 エンドポイント アドレスの前にこのパラメーターがないと、このコマンドに対する応答は、応答が発生しなかった場合と同様に空のままになります。

応答の例

HTTP/2 202
content-length: 0
operation-location: https://southcentralus.api.cognitive.microsoft.com:443/language/query-knowledgebases/projects/Sample-project/qnas/jobs/{JOB-ID-GUID}
x-envoy-upstream-service-time: 507
apim-request-id: 
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Wed, 24 Nov 2021 03:16:01 GMT

質問応答ペアの更新状態を取得する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME 質問応答ペアの更新先として使用するプロジェクトの名前。
JOB-ID 質問応答ペアをプログラムによって更新すると、更新要求への operation-location 応答ヘッダーの一部として JOB-ID が生成されます。 JOB-ID は、operation-location の末尾にある GUID です。 例: operation-location: https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/sample-proj1/qnas/jobs/{THIS GUID IS YOUR JOB ID}

クエリの例

curl -X GET -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '' 'https://southcentralus.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/qnas/jobs/{JOB-ID}?api-version=2021-10-01'

応答の例

  "createdDateTime": "2021-11-24T03:16:01+00:00",
  "expirationDateTime": "2021-11-24T09:16:01+00:00",
  "jobId": "{JOB-ID-GUID}",
  "lastUpdatedDateTime": "2021-11-24T03:16:06+00:00",
  "status": "succeeded",
  "resultUrl": "/knowledgebases/Sample-project"

シノニムを更新する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME シノニムを追加するプロジェクトの名前。

クエリの例

curl -X PUT -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '{
"value": [
    {
      "alterations": [
        "qnamaker",
        "qna maker"
      ]
    },
    {
      "alterations": [
        "botframework",
        "bot framework"
      ]
    }
  ]
}' -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/synonyms?api-version=2021-10-01'

応答の例

0HTTP/2 200
content-length: 17
content-type: application/json; charset=utf-8
x-envoy-upstream-service-time: 39
apim-request-id: 5deb2692-dac8-43a8-82fe-36476e407ef6
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Wed, 24 Nov 2021 03:59:09 GMT

{
  "value": []
}

アクティブ ラーニングのフィードバックを更新する

変数名 値
ENDPOINT この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 エンドポイントの例: https://southcentralus.api.cognitive.microsoft.com/。 これが次のコード サンプルのエンドポイントである場合、残りのエンドポイント パスは既に指定されているため、リージョン固有の部分である southcentral のみを追加する必要があります。
API-KEY この値は、Azure portal からリソースを確認する際に、 [Keys & Endpoint](キーとエンドポイント) セクションで確認することができます。 Key1 または Key2 を使用できます。 常に 2 つの有効なキーを持つことで、ダウンタイムなしで安全にキーのローテーションを行うことができます。 または、[Language Studio]>[質問応答]>[プロジェクトのデプロイ]>[Get prediction URL] (予測 URL の取得) で値を見つけることができます。 キー値は、サンプル要求の一部です。
PROJECT-NAME アクティブ ラーニングのフィードバックの更新先として使用するプロジェクトの名前。

クエリの例

curl -X POST -H "Ocp-Apim-Subscription-Key: {API-KEY}" -H "Content-Type: application/json" -d '{
records": [
    {
      "userId": "user1",
      "userQuestion": "hi",
      "qnaId": 1
    },
    {
      "userId": "user1",
      "userQuestion": "hello",
      "qnaId": 2
    }
  ]
}' -i 'https://{ENDPOINT}.api.cognitive.microsoft.com/language/query-knowledgebases/projects/{PROJECT-NAME}/feedback?api-version=2021-10-01'

応答の例

HTTP/2 204
x-envoy-upstream-service-time: 37
apim-request-id: 92225e03-e83f-4c7f-b35a-223b1b0f29dd
strict-transport-security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
date: Wed, 24 Nov 2021 04:02:56 GMT