获取批量听录结果

项目
09/19/2024

若要获取听录结果，请先检查听录作业的状态。如果作业已完成，则可以检索听录内容和听录报告。

获取听录状态

若要获取听录作业的状态，请调用语音转文本 REST API 的 Transcriptions_Get 操作。

重要

批量听录作业是按“尽力而为”的原则安排的。在高峰时段，听录作业可能需要长达 30 分钟或更长时间才能开始处理。在执行期间的大部分时间，听录状态为 Running。这是因为作业在移动到批处理听录后端系统的那一刻就被分配了 Running 状态。使用基本模型时，此分配几乎立即发生，而自定义模型的速度略慢。因此，听录作业处于 Running 状态的时间与实际听录时间不符，而是同时包含了在内部队列中的等待时间。

使用 URI 提出 HTTP GET 请求，如以下示例所示。将 YourTranscriptionId 替换为事务 ID，将 YourSubscriptionKey 替换为语音资源密钥，将 YourServiceRegion 替换为语音资源区域。

curl -v -X GET "https://YourServiceRegion.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/YourTranscriptionId" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

你应该会收到以下格式的响应正文：

{
  "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3",
  "model": {
    "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/models/base/aaa321e9-5a4e-4db1-88a2-f251bbe7b555"
  },
  "links": {
    "files": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "displayFormWordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "duration": "PT3S",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2024-05-10T18:39:09Z",
  "status": "Succeeded",
  "createdDateTime": "2024-05-10T18:39:07Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

status 属性指示听录的当前状态。听录和听录报告在听录状态为 Succeeded 时可用。

重要

若要获取听录作业的状态，请使用 spx batch transcription status 命令。根据以下说明构造请求参数：

将 transcription 参数设置为你要获取的听录的 ID。

下面是用于获取听录状态的语音 CLI 命令示例：

spx batch transcription status --api-version v3.2 --transcription YourTranscriptionId

你应该会收到以下格式的响应正文：

{
  "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3",
  "model": {
    "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/models/base/aaa321e9-5a4e-4db1-88a2-f251bbe7b555"
  },
  "links": {
    "files": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "displayFormWordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "duration": "PT3S"
  },
  "lastActionDateTime": "2024-05-10T18:39:09Z",
  "status": "Succeeded",
  "createdDateTime": "2024-05-10T18:39:07Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

status 属性指示听录的当前状态。听录和听录报告在听录状态为 Succeeded 时可用。

要获取听录的语音 CLI 帮助，请运行以下命令：

spx help batch transcription

获取听录结果

Transcriptions_ListFiles 操作可返回听录的结果文件列表。为每个提交的批量听录作业提供听录报告文件。此外，为每个成功转录的音频文件提供一个听录文件（最终结果）。

使用上一个响应正文中的“files”URI 发出 HTTP GET 请求。将 YourTranscriptionId 替换为事务 ID，将 YourSubscriptionKey 替换为语音资源密钥，将 YourServiceRegion 替换为语音资源区域。

curl -v -X GET "https://YourServiceRegion.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/YourTranscriptionId/files" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

你应该会收到以下格式的响应正文：

{
  "values": [
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/2dd180a1-434e-4368-a1ac-37350700284f",
      "name": "contenturl_0.json",
      "kind": "Transcription",
      "properties": {
        "size": 3407
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionUrl"
      }
    },
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/c027c6a9-2436-4303-b64b-e98e3c9fc2e3",
      "name": "contenturl_1.json",
      "kind": "Transcription",
      "properties": {
        "size": 8233
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionUrl"
      }
    },
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/faea9a41-c95c-4d91-96ff-e39225def642",
      "name": "report.json",
      "kind": "TranscriptionReport",
      "properties": {
        "size": 279
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionReportUrl"
      }
    }
  ]
}

每个转录的位置和具有更多详细信息的转录报告文件将在响应正文中返回。 contentUrl 属性包含听录 ("kind": "Transcription") 或转录报告 ("kind": "TranscriptionReport") 文件的 URL。

如果未在转录请求的 destinationContainerUrl 属性中指定容器，则结果将存储在 Microsoft 管理的容器中。删除听录作业时，结果数据也会被删除。

spx batch transcription list 命令返回听录的结果文件列表。为每个提交的批量听录作业提供听录报告文件。此外，为每个成功转录的音频文件提供一个听录文件（最终结果）。

设置所需的 files 标志。
将所需的 transcription 参数设置为要获取日志的听录的 ID。

下面是一个语音 CLI 命令示例，用于获取听录的结果文件列表：

spx batch transcription list --api-version v3.2 --files --transcription YourTranscriptionId

你应该会收到以下格式的响应正文：

{
  "values": [
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/2dd180a1-434e-4368-a1ac-37350700284f",
      "name": "contenturl_0.json",
      "kind": "Transcription",
      "properties": {
        "size": 3407
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionUrl"
      }
    },
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/c027c6a9-2436-4303-b64b-e98e3c9fc2e3",
      "name": "contenturl_1.json",
      "kind": "Transcription",
      "properties": {
        "size": 8233
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionUrl"
      }
    },
    {
      "self": "https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.2/transcriptions/637d9333-6559-47a6-b8de-c7d732c1ddf3/files/faea9a41-c95c-4d91-96ff-e39225def642",
      "name": "report.json",
      "kind": "TranscriptionReport",
      "properties": {
        "size": 279
      },
      "createdDateTime": "2024-05-10T18:39:09Z",
      "links": {
        "contentUrl": "YourTranscriptionReportUrl"
      }
    }
  ]
}

默认情况下，结果存储在 Microsoft 管理的容器中。删除听录作业时，结果数据也会被删除。

听录报告文件

系统将为每个提交的批听录作业提供一个听录报告文件。

每个听录结果文件的内容都格式化为 JSON，如本示例所示。

{
  "successfulTranscriptionsCount": 2,
  "failedTranscriptionsCount": 0,
  "details": [
    {
      "source": "https://crbn.us/hello.wav",
      "status": "Succeeded"
    },
    {
      "source": "https://crbn.us/whatstheweatherlike.wav",
      "status": "Succeeded"
    }
  ]
}

听录结果文件

系统将为每个成功听录的音频文件提供一个听录结果文件。

每个听录结果文件的内容都格式化为 JSON，如本示例所示。

{
  "source": "...",
  "timestamp": "2023-07-10T14:28:16Z",
  "durationInTicks": 25800000,
  "duration": "PT2.58S",
  "combinedRecognizedPhrases": [
    {
      "channel": 0,
      "lexical": "hello world",
      "itn": "hello world",
      "maskedITN": "hello world",
      "display": "Hello world."
    }
  ],
  "recognizedPhrases": [
    {
      "recognitionStatus": "Success",
      "channel": 0,
      "offset": "PT0.76S",
      "duration": "PT1.32S",
      "offsetInTicks": 7600000.0,
      "durationInTicks": 13200000.0,
      "nBest": [
        {
          "confidence": 0.5643338,
          "lexical": "hello world",
          "itn": "hello world",
          "maskedITN": "hello world",
          "display": "Hello world.",
          "displayWords": [
            {
              "displayText": "Hello",
              "offset": "PT0.76S",
              "duration": "PT0.76S",
              "offsetInTicks": 7600000.0,
              "durationInTicks": 7600000.0
            },
            {
              "displayText": "world.",
              "offset": "PT1.52S",
              "duration": "PT0.56S",
              "offsetInTicks": 15200000.0,
              "durationInTicks": 5600000.0
            }
          ]
        },
        {
          "confidence": 0.1769063,
          "lexical": "helloworld",
          "itn": "helloworld",
          "maskedITN": "helloworld",
          "display": "helloworld"
        },
        {
          "confidence": 0.49964225,
          "lexical": "hello worlds",
          "itn": "hello worlds",
          "maskedITN": "hello worlds",
          "display": "hello worlds"
        },
        {
          "confidence": 0.4995761,
          "lexical": "hello worm",
          "itn": "hello worm",
          "maskedITN": "hello worm",
          "display": "hello worm"
        },
        {
          "confidence": 0.49418187,
          "lexical": "hello word",
          "itn": "hello word",
          "maskedITN": "hello word",
          "display": "hello word"
        }
      ]
    }
  ]
}

听录文件可以包含以下结果属性，而且部分取决于创建听录作业时设置的请求参数。

属性	说明
`channel`	结果的通道号。对于立体声音频流，在听录期间会拆分左右声道。为每个输入音频文件创建一个 JSON 结果文件。
`combinedRecognizedPhrases`	通道的所有短语的串联结果。
`confidence`	识别的置信度值。
`display`	已识别文本的显示形式。包括添加的标点和大小写。
`displayWords`	听录的每个单词的时间戳。必须将 `displayFormWordLevelTimestampsEnabled` 请求属性设置为 `true`，否则此属性不存在。注意：此属性仅适用于语音转文本 REST API 版本 3.1 及更高版本。
`duration`	音频持续时间。该值是 ISO 8601 编码持续时间。
`durationInTicks`	以时钟周期为单位的音频持续时间（1 个时钟周期是 100 纳秒）。
`itn`	已识别文本的反向文本规范化 (ITN) 形式。已应用缩写（如“Doctor Smith”缩写为“Dr Smith”）、电话号码和其他转换。
`lexical`	识别的实际单词。
`locale`	从音频输入中标识的区域设置。必须设置 `languageIdentification` 请求属性，否则此属性不存在。注意：此属性仅适用于语音转文本 REST API 版本 3.1 及更高版本。
`maskedITN`	应用了亵渎内容屏蔽的 ITN 形式。
`nBest`	带有置信度的当前短语的可能听录列表。
`offset`	此短语音频中的偏移量。该值是 ISO 8601 编码持续时间。
`offsetInTicks`	此短语的音频偏移量，以时钟周期为单位（1 个时钟周期为 100 纳秒）。
`recognitionStatus`	识别状态。例如：“成功”或“失败”。
`recognizedPhrases`	每个短语的结果列表。
`source`	作为输入音频源提供的 URL。源对应于 `contentUrls` 或 `contentContainerUrl` 请求属性。 `source` 属性是确认听录音频输入的唯一方法。
`speaker`	已识别的说话人。必须设置 `diarization` 和 `diarizationEnabled` 请求属性，否则此属性不存在。
`timestamp`	听录的创建日期和时间。该值是 ISO 8601 编码时间戳。
`words`	结果的列表，其中包含短语的每个单词的词法文本。必须将 `wordLevelTimestampsEnabled` 请求属性设置为 `true`，否则此属性不存在。

通过

获取批量听录结果

获取听录状态

获取听录结果

听录报告文件

听录结果文件

后续步骤

其他资源