Gridwich の要求 - 応答メッセージ

Azure Logic Apps
Azure Storage

この記事では、さまざまな Gridwich 操作の要求 - 応答シーケンスを形成する特定の Event Grid イベントについて詳しく説明します。

Gridwich イベント

Gridwich 受信確認と Gridwich エラーは、他の Gridwich イベントとは異なります。 具体的な内容は次のとおりです。

  • Gridwich 受信確認 (ACK) は、要求 - ACK - 応答シーケンスの要求が Gridwich で受信された (ただし、必ずしも処理されたとは限らない) ことを示します。
  • 各操作には固有の成功応答イベントが 1 つまたは複数ありますが、ほぼすべての操作が同じ Gridwich エラー イベントを使用してエラーを通知します。

エンコードのイベント

BLOB およびコンテナーの保存のイベント

ストレージ キー

操作コンテキスト

Gridwich では、要求メッセージの一部として JSON operationContext オブジェクトが受け入れられます。 Gridwich では一般に、対応するオブジェクトが応答メッセージでエコーされ、その際にコンテキスト オブジェクトの特定の内部構造や内容は考慮されません。

例外として、応答のコンテキスト オブジェクトは、要求の同等のものと比較して、追加の JSON プロパティを含む可能性があります。 これらの追加プロパティは Gridwich 内部のもので、その名前は常にチルダ ~ 文字で始まります。 要求のプロパティは、常に応答のコンテキスト オブジェクトに存在します。

通常の JSON と同様、応答オブジェクトのプロパティの出現順序は、要求オブジェクトのものとは異なることがあります。

操作コンテキストの詳細については、Gridwich アーキテクチャの記事の操作コンテキストに関するページを参照してください。

Event Grid メッセージ

要求 - 応答メッセージ フローの詳細については、アーキテクチャ要求フローに関するページを参照してください。

次のイベントの説明では、JSON プロパティの値は通常の文字列、数値、またはブール型です。 説明では、次の特定の文字列コンテンツ タイプを使用します。 説明に "不透明" が含まれている場合、その値のコンテンツと形式は任意です。

  • GUID-string は、"b621f33d-d01e-0002-7ae5-4008f006664e" のような 16 バイトの ID 値であり、36 文字 (32 の 16 進数と 4 つのダッシュ) で表されます。 中かっこがないことに注意してください。 値の大文字と小文字は区別されません。 この形式は、System.GUID.ToString("D") の結果に対応しています。
  • Topic-string は、"/subscriptions/5edeadbe-ef64-4022-a3aa-133bfef1d7a2/resourceGroups/gws-shared-rg-sb/providers/Microsoft.EventGrid/topics/gws-gws-egt-sb" のような、不透明コンテンツの文字列です。
  • Subject-string は、"/blobServices/default/containers/telestreamoutput/blobs/db08122195b66be71db9e54ae04c58df/503220533TAGHD23976fps16x990266772067587.mxf" のような、不透明コンテンツの文字列です。
  • EventType-string は、"request.operation.requested" のように、通常は {"request"|"response"}.operation[.qualifier] という形式の文字列です。
  • DataVersion-string は、"1.0" のようなバージョン管理インジケーターであり、同じ操作の異なる進化を区別するためにメッセージ プロセッサで使用されます。 Gridwich には、このフィールドが必要です。 HandlesEvent メソッドは、個々の Event Grid ハンドラーで処理できるバージョンを決定します。
  • URL-string は絶対 URL で、多くの場合 Application Insights のログを指します。 対象の認可要件により、通常これらの文字列は SAS URL です。
  • StorageURL-string は絶対 URL で、多くの場合 Azure Storage Blob またはコンテナーを指します。 通常、この文字列は SAS URL ではありません。
  • StorageURL-SAS-string は絶対 SAS URL で、多くの場合 Azure Storage Blob またはコンテナーを指します。
  • OperationContextObject は、{ "prodID": 10, "dc": "abc" } のような、受信要求で受け入れられ Gridwich 応答イベントの一部としてエコー バックされる、任意の JSON オブジェクトです。
  • Metadata-Dictionary は、Azure Storage Blob のメタデータを表す名前と値のペアを持つ、文字列から文字列への JSON オブジェクト ディクショナリです。
  • Encoder-Context は、特定のエンコーダーに固有のプロパティから成る不透明な JSON オブジェクトです。

Gridwich 汎用 ACK 応答

Gridwich>要求者では、ResponseAcknowledgeDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "eventType": "request.blob.metadata.create"
    },
    "eventType": "response.acknowledge"
}

data.eventType 文字列の値は、要求イベントの最上位の eventType プロパティです。 たとえば、BLOB 分析要求の場合、 data.eventType 文字列の値は request.blob.analysis.create です。

Gridwich 汎用エラー応答

Gridwich>要求者では、ResponseFailureDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "logEventId": 30001,
        "logEventMessage": "the message text for eventId 30001",
        "logRecordId": "GUID-string",
        "logRecordUrl": "URL-string", // AppInsight URL to the logRecordId
        "eventHandlerClassName": "string",
        "handlerId": "GUID-string"
    },
    "eventType": "response.failure"
}

エラー イベントには、元の要求の eventType 値は含まれませんが、操作コンテキストと、要求を処理していたハンドラー名が含まれます。 log* プロパティは、構成済みの Application Insights インスタンスによって記録された問題の情報に関連しています。

一部の操作では、失敗イベント オブジェクトが前のメッセージと大幅に異なります。 詳細については、ストレージ キーのローテーションに関するページを参照してください。

要求者が Gridwich に、いくつかのメタデータを BLOB に配置するように要求する

要求者>Gridwich では、RequestBlobMetadataCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "blobMetadata": <Metadata-Dictionary>
    },
    "eventType": "request.blob.metadata.create"
}

blobMetadata は、必要な BLOB メタデータのすべての名前と値のペアを表す文字列値プロパティから成るオブジェクトです。

要求者>Gridwich では、ResponseBlobMetadataSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "blobMetadata": <Metadata-Dictionary>
    },
    "eventType": "response.blob.metadata.success"
}

BLOB の現在のメタデータを後で取得するには、BLOB の分析要求を参照してください。

要求者が Gridwich に、MediaInfo を使用して BLOB の分析を実行するように要求する

要求者>Gridwich では、RequestBlobAnalysisCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "analyzerSpecificData": {
            "mediaInfo": {
                  "commandLineOptions": {
                    "Complete": "1",
                    "Output": "JSON"
                  }
            }
        }
    },
    "eventType": "request.blob.analysis.create"
}

Gridwich>要求者では、ResponseBlobAnalysisSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "blobMetadata": <Metadata-Dictionary>,
        "analysisResults": <Analysis-Result-Object>
    },
    "eventType": "response.blob.analysis.success"
}

analysisResults オブジェクトのコンテンツは指定されていません。 現在のプロジェクトでは、MediaInfo の出力です。

blobMetadata の値は、指定された BLOB メタデータのすべての名前と値のペアを表す文字列値プロパティから成る、文字列から文字列へのディクショナリ オブジェクトです。

Azure Storage での通常どおり、メタデータ項目の名前は C# の識別子の名前付け規則に従っている必要があります。 詳細については、Azure の SetBlobMetadata REST API および C# の名前付け規則に関するページを参照してください。

要求者が Gridwich に、BLOB を新しい宛先にコピーするように要求する

要求者>Gridwich では、RequestBlobCopyDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "sourceUri": "StorageURL-string",
        "destinationUri": "StorageURL-string"
    },
    "eventType": "request.blob.copy"
}

Gridwich>要求者では、ResponseBlobCopyScheduledDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "sourceUri": "URL-string",
        "blobMetadata": <Metadata-Dictionary>,
        "destinationUri": "StorageURL-string"
    },
    "eventType": "response.blob.copy.scheduled"
}

Gridwich が要求者に、BLOB を作成したことを通知する

Gridwich では、コピーの結果、受信トレイへの到着、エンコードの結果など、任意のソースから BLOB が作成された可能性があります。

Gridwich>要求者では、ResponseBlobCreatedSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "blobMetadata": <Metadata-Dictionary>
    },
    "eventType": "response.blob.created.success"
}

要求者が Gridwich に、BLOB を削除するように要求する

要求者>Gridwich では、RequestBlobDeleteDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
    },
    "eventType": "request.blob.delete"
}

Gridwich>要求者では、ResponseBlobDeleteScheduledDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "blobMetadata": <Metadata-Dictionary>
    },
    "eventType": "response.blob.delete.scheduled"
}

Gridwich が要求者に、BLOB を削除したことを通知する

BLOB の削除は、要求者からの明示的な要求や、内部操作の結果など、任意のソースから発生する可能性があります。

Gridwich>要求者では、ResponseBlobDeleteSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string"
    },
    "eventType": "response.blob.delete.success"
}

要求者が Gridwich に、有効期限切れのコンテンツの SAS URL を返すように要求する

要求者>Gridwich では、RequestBlobSasUrlCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "secToLive": 1200
    },
    "eventType": "request.blob.sas-url.create"
}

Gridwich>要求者では、ResponseBlobSasUrlSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "sasUrl": "StorageURL-SAS-string"
    },
    "eventType": "response.blob.sas-url.success"
}

要求者が Gridwich に、CloudPort ワークフローでエンコードするように要求する

要求者>Gridwich では、RequestCloudPortEncodeCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
          "inputs": [
                {"blobUri": "StorageURL-string" }
          ],
          "outputContainer": "https://<storageaccountname>.blob.core.windows.net/<containername>/",
          "workflowName": "TestWorkflow2",
          "parameters": [ { "prop1": "value1" } ],
           "secToLive": 18000
  },
  "eventType": "request.encode.cloudport.create",
}

要求者が Gridwich に、Flip でエンコードするように要求する

要求者>Gridwich では、RequestFlipEncodeCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
          "inputs": [
                {"blobUri": "StorageURL-string" }
          ],
          "outputContainer": "StorageURL-string", // of the Storage container
          "factoryName": "gws-dev-flip",
          "profiles": "h264",
          "parameters": [ { "prop1": "value1" } ],
           "secToLive": 18000
      },
      "eventType": "request.encode.flip.create"
}

RequestFlipEncodeCreateDTO の例

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": { "progId": 1234 },
          "inputs": [
            {
                "blobUri": "https://gws-sa1.blob.core.windows.net/Vid0001Container/input.mp4"
            }
          ],
          "outputContainer": "https://gws-sa22out.blob.core.windows.net/Out0004/",
          "factoryName": "gws-dev-flip",
          "profiles": "h264",
          "parameters": [ { "someProperty1": "someValue1" } ],
          "secToLive": 18000
      },
      "eventType": "request.encode.flip.create"
}

Gridwich エンコーダーの一般的な要求のディスパッチ成功応答

Gridwich>要求者では、ResponseEncodeDispatchedDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "encoderContext": <EncoderContext>,
        "workflowJobName": "CloudPort or Flip assigned job name for workflow instance."
    },
    "eventType": "response.encode.<encodername>.dispatched"
}

<encodername> は、、、cloudportまたは flip のいずれかです。

Gridwich エンコーダーの非同期ステータス メッセージ

Gridwich エンコーダーでは、エンコードの途中または終了時に、次の 4 種類のイベントが生成されます。

  • スケジュール
  • 処理中
  • Success
  • Canceled

エンコード要求エラーが発生すると、Gridwich エラー イベントが生成されます。

エンコードの状態: スケジュール済み

Gridwich>要求者では、ResponseEncodeScheduledDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "encoderContext":  <EncoderContext>,
        "workflowJobName": "CloudPort or Flip assigned job name for workflow instance."
    },
    "eventType": "response.encode.<encodername>.scheduled"
}

エンコードの状態: 処理中

Gridwich>要求者では、ResponseEncodeProcessingDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "encoderContext": <EncoderContext>,
        "workflowJobName": "CloudPort or Flip assigned job name for workflow instance.",
        "currentStatus": "string",
        "percentComplete": 50,
    },
    "eventType": "response.encode.<encodername>.processing"
}

エンコードの状態: 成功

Gridwich>要求者では、ResponseEncodeSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,,
        "encoderContext": <EncoderContext>,
        "workflowJobName": "CloudPort or Flip assigned job name for workflow instance.",
        "outputs":[
            { "blobUri": "StorageURL-string" }
        ]
    },
    "eventType": "response.encode.<encodername>.success"
}

エンコードの状態: キャンセル済み

Gridwich>要求者では、ResponseEncodeCanceledDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "encoderContext": <EncoderContext>,
        "workflowJobName": "CloudPort or Flip assigned job name for workflow instance."
    },
    "eventType": "response.encode.<encodername>.canceled"
}

要求者が Gridwich に、BLOB のストレージ層を変更するように要求する

要求者>Gridwich では、RequestBlobTierChangeDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "accessTier": "string",
        "rehydratePriority": "string"
    },
    "eventType": "request.blob.tier.change"
}
  • accessTier プロパティは、HotCool、または Archive です。
  • rehydratePriority プロパティは、Standard または High です。

Gridwich>要求者では、ResponseBlobTierChangeSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "blobUri": "StorageURL-string",
        "accessTier": "string",
        "rehydratePriority": "string"
    },
    "eventType":"response.blob.tier.success"
}

要求者が Gridwich に、BLOB コンテナーを作成するように要求する

要求では、ストレージ アカウントとコンテナー名を指定します。

要求者>Gridwich では、RequestContainerCreateDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string", // e.g. mySA1
        "containerName": "string"       // e.g. mycontainer
    },
    "eventType": "request.blob.container.create"
}

Gridwich>要求者では、ResponseContainerCreatedSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string",
        "containerName": "string"
    },
    "eventType": "response.blob.container.create.success"
}

要求者が Gridwich に、BLOB コンテナーを削除するように要求する

要求では、ストレージ アカウントとコンテナー名を指定します。

要求者>Gridwich では、RequestContainerDeleteDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string",
        "containerName": "string"
    },
    "eventType": "request.blob.container.delete"
}

Gridwich>要求者では、ResponseContainerDeleteSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string",
        "containerName": "string"
    },
    "eventType": "response.blob.container.delete.success"
}

要求者が Gridwich に、コンテナーのパブリック アクセスを変更するように要求する

要求では、コンテナー名と accessType (BlobBlobContainer、または None) を指定します。

要求者>Gridwich では、RequestContainerAccessChangeDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string",
        "containerName": "string",
        "accessType": "string"
    },
    "eventType": "request.blob.container.access.change"
}

Gridwich>要求者では、ResponseContainerAccessChangeSuccessDTO が使用されます。

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "storageAccountName": "string",
        "containerName": "string",
        "accessType": "string"
    },
    "eventType": "response.blob.container.access.change.success"
}

要求者が Gridwich に、新しいストレージ キーにローテーションするように要求する

Rollkey イベント ファミリは、operationContext 値が要求では受け入れられるが応答イベントには含まれないという点で、Gridwich の他のイベント ファミリとは異なります。

エラー イベントのイベントの種類は、通常の response.failure ではなく、response.rollkey.storage.failure という値を持ちます。

response.rollkey.storage.failure エラー イベントは次のとおりです。

  • 通常のエラー イベント ログ情報の log データ プロパティは含まれていません。
  • エラー メッセージ テキストを含む、error という名前の追加のデータ プロパティが含まれています。 その他の Gridwich エラーでは、そのテキストが logEventMessage データ プロパティに格納されます。

これらのポイントには、RollKey 操作を実行する Azure ロジック アプリの現在の状態が反映されます。 ロジックアプリの定義は、infrastructure/terraform/keyroller/main.tf Terraform ファイルにあります。

keyName は、Azure Storage のkeyName操作で定義されているキーの名前に対応します。

要求者>Gridwich

{
    "id": "GUID-string",
    "topic": "Topic-string",
    "subject": "Subject-string",
    "dataVersion": "DataVersion-string",
    "data": {
        "operationContext": <OperationContextObject>,
        "account": "storageAccountName",
        "keyName": "key1"
    },
    "eventType": "request.rollkey.storage"
}

Gridwich>要求者

  • 成功:

    {
        "id": "GUID-string",
        "topic": "Topic-string",
        "subject": "Subject-string",
        "dataVersion": "DataVersion-string",
        "data": {
            "account": "storageAccountName",
            "keyName": "key1"
        },
        "eventType": "response.rollkey.storage.success"
    }
    
  • 失敗:

    {
        "id": "GUID-string",
        "topic": "Topic-string",
        "subject": "Subject-string",
        "dataVersion": "1.0",
        "data": {
           "account": "storageAccountName1",
            "keyName": "key1",
            "error": "error message text"
        },
        "eventType": "response.rollkey.storage.failure"
    }
    

    この操作の失敗の結果は、通常の Gridwich エラーほど完全ではありません。

次の手順

製品ドキュメント:

Microsoft Learn モジュール: