Azure Logic Apps における各種コンテンツの扱いHandle content types in Azure Logic Apps

ロジック アプリには、JSON、XML、フラット ファイル、バイナリ データなど、さまざまな種類のコンテンツを渡すことができます。Various content types can flow through a logic app, for example, JSON, XML, flat files, and binary data. Logic Apps はあらゆるコンテンツ タイプをサポートしています。ネイティブでサポートされるコンテンツ タイプもあり、その場合は、ロジック アプリ側でのキャストや変換は不要です。While Logic Apps supports all content types, some have native support and don't require casting or conversion in your logic apps. 一方、必要に応じてキャストまたは変換が必要なコンテンツ タイプもあります。Other types might require casting or conversion as necessary. この記事では、Logic Apps による各種コンテンツの扱いと、それらを必要に応じて正しくキャストまたは変換する方法について説明します。This article describes how Logic Apps handles content types and how you can correctly cast or convert these types when necessary.

Logic Apps では各種コンテンツの適切な処理方法を判断するために、HTTP 呼び出しに含まれる Content-Type ヘッダーの値が使用されます。その例を次に示します。To determine the appropriate way for handling content types, Logic Apps relies on the Content-Type header value in HTTP calls, for example:

application/jsonapplication/json

Logic Apps は、コンテンツ タイプが application/json であるすべての要求を JavaScript Notation (JSON) オブジェクトとして格納して処理します。Logic Apps stores and handles any request with the application/json content type as a JavaScript Notation (JSON) object. JSON コンテンツは、キャストせずに既定で解析することができます。By default, you can parse JSON content without any casting. "application/json" コンテンツ タイプのヘッダーを含む要求は、式を使って解析できます。To parse a request that has a header with the "application/json" content type, you can use an expression. 次の例では、animal-type 配列から、キャストなしで dog という値が返されます。This example returns the value dog from the animal-type array without casting:

@body('myAction')['animal-type'][0]

{
  "client": {
     "name": "Fido",
     "animal-type": [ "dog", "cat", "rabbit", "snake" ]
  }
}

ヘッダーが指定されない JSON データを扱う場合は、次の例のように json() 関数を使って、データを手動で JSON にキャストすることができます。If you're working with JSON data that doesn't specify a header, you can manually cast that data to JSON by using the json() function, for example:

@json(triggerBody())['animal-type']

JSON のプロパティに使用するトークンの作成Create tokens for JSON properties

Logic Apps には、JSON コンテンツのプロパティをロジック アプリのワークフローの中で簡単に参照して使用できるように、そうしたプロパティを表すユーザー フレンドリなトークンを生成する機能が用意されています。Logic Apps provides the capability for you to generate user-friendly tokens that represent the properties in JSON content so you can reference and use those properties more easily in your logic app's workflow.

  • 要求トリガーRequest trigger

    ロジック アプリ デザイナーでは、このトリガーを使って、受け取りたいペイロードを表す JSON スキーマを指定することができます。When you use this trigger in the Logic App Designer, you can provide a JSON schema that describes the payload you expect to receive. デザイナーは、このスキーマを使って JSON コンテンツを解析することにより、JSON コンテンツ内の各種プロパティを表すユーザー フレンドリなトークンを生成します。The designer parses JSON content by using this schema and generates user-friendly tokens that represent the properties in your JSON content. その後、ロジック アプリのワークフローの至る所で、これらのプロパティを簡単に参照して使用することができます。You can then easily reference and use those properties throughout your logic app's workflow.

    スキーマがない場合は、自分で生成することができます。If you don't have a schema, you can generate the schema.

    1. 要求トリガーで [サンプルのペイロードを使用してスキーマを生成する] を選択します。In the Request trigger, select Use sample payload to generate schema.

    2. [サンプルの JSON ペイロードを入力するか、貼り付けます] でサンプル ペイロードを指定し、 [完了] を選択します。Under Enter or paste a sample JSON payload, provide a sample payload and then choose Done. 例:For example:

      サンプル JSON ペイロードの指定

      生成されたスキーマがトリガーに表示されます。The generated schema now appears in your trigger.

      サンプル JSON ペイロードの指定

      コード ビュー エディターでは、この要求トリガーの基になる定義が次のように表示されます。Here is the underlying definition for your Request trigger in the code view editor:

      "triggers": { 
         "manual": {
            "type": "Request",
            "kind": "Http",
            "inputs": { 
               "schema": {
                  "type": "object",
                  "properties": {
                     "client": {
                        "type": "object",
                        "properties": {
                           "animal-type": {
                              "type": "array",
                              "items": {
                                 "type": "string"
                              },
                           },
                           "name": {
                              "type": "string"
                           }
                        }
                     }
                  }
               }
            }
         }
      }
      
    3. 要求には必ず Content-Type ヘッダーを追加し、その値を application/json に設定してください。In your request, make sure you include a Content-Type header and set the header's value to application/json.

  • Parse JSON アクションParse JSON action

    ロジック アプリ デザイナーでは、このアクションを使って JSON 出力を解析し、JSON コンテンツ内の各種プロパティを表すユーザー フレンドリなトークンを生成することができます。When you use this action in the Logic App Designer, you can parse JSON output and generate user-friendly tokens that represent the properties in your JSON content. その後、ロジック アプリのワークフローの至る所で、これらのプロパティを簡単に参照して使用することができます。You can then easily reference and use those properties throughout your logic app's workflow. 要求トリガーと同様、解析したい JSON コンテンツの JSON スキーマを指定または生成することができます。Similar to the Request trigger, you can provide or generate a JSON schema that describes the JSON content you want to parse. これにより、Azure Service Bus や Azure Cosmos DB などのデータが利用しやすくなります。That way, you can more easily consume data from Azure Service Bus, Azure Cosmos DB, and so on.

    JSON の解析

text/plaintext/plain

ロジック アプリは、Content-Type ヘッダーが text/plain に設定された HTTP メッセージを受信すると、それらのメッセージを生の形式で格納します。When your logic app receives HTTP messages that have the Content-Type header set to text/plain, your logic app stores those messages in raw form. それらのメッセージをキャストせずに後続のアクションに追加した場合、Content-Type ヘッダーが text/plain に設定された状態で要求が送信されます。If you include these messages in subsequent actions without casting, requests go out with the Content-Type header set to text/plain.

たとえばフラット ファイルを扱っているときに、Content-Type ヘッダーが text/plain コンテンツ タイプに設定された次のような HTTP 要求を受け取ったとします。For example, when you're working with a flat file, you might get an HTTP request with the Content-Type header set to text/plain content type:

Date,Name,Address
Oct-1,Frank,123 Ave

その後、この要求を後続のアクションの中で、別の要求の本文として送信した場合 (@body('flatfile') など)、その 2 つ目の要求の Content-Type ヘッダーも text/plain に設定されます。If you then send this request on in a later action as the body for another request, for example, @body('flatfile'), that second request also has a Content-Type header that's set to text/plain. プレーンテキストではあるもののヘッダーが指定されていないデータを扱う場合、次の式のように、string() 関数を使えば、そのデータを手動でテキストにキャストすることができます。If you're working with data that is plain text but didn't specify a header, you can manually cast that data to text by using the string() function such as this expression:

@string(triggerBody())

application/xml と application/octet-streamapplication/xml and application/octet-stream

Logic Apps は、HTTP 要求または HTTP 応答で受信した Content-Type を常に維持します。Logic Apps always preserves the Content-Type in a received HTTP request or response. そのため、Content-Typeapplication/octet-stream に設定したコンテンツがロジック アプリによって受信されたとき、そのコンテンツをキャストせずに後続のアクションに渡した場合、そこから送信される要求の Content-Typeapplication/octet-stream に設定されます。So if your logic app receives content with Content-Type set to application/octet-stream, and you include that content in a later action without casting, the outgoing request also has Content-Type set to application/octet-stream. こうすることで、ワークフロー内を移動する過程でデータが失われないことを Logic Apps は保証することができます。That way, Logic Apps can guarantee that data doesn't get lost while moving through the workflow. ただし、アクションの状態 (入力と出力) は、ワークフローを移動する間、JSON オブジェクトに格納されます。However, the action state, or inputs and outputs, is stored in a JSON object while the state moves through the workflow.

コンバーター関数Converter functions

Logic Apps は一部のデータ型について、その型を維持するために、$content ペイロードと $content-type の両方を保持する適切なメタデータを含む、Base64 でエンコードされたバイナリ文字列にコンテンツを変換します (自動的に変換される)。To preserve some data types, Logic Apps converts content to a binary base64-encoded string with appropriate metadata that preserves both the $content payload and the $content-type, which are automatically converted.

以下に示したのは、変換関数を使ったときに、Logic Apps によってコンテンツがどのように変換されるかを箇条書きにしたものです。This list describes how Logic Apps converts content when you use these functions:

  • json():データを application/json にキャストしますjson(): Casts data to application/json
  • xml():データを application/xml にキャストしますxml(): Casts data to application/xml
  • binary():データを application/octet-stream にキャストしますbinary(): Casts data to application/octet-stream
  • string():データを text/plain にキャストしますstring(): Casts data to text/plain
  • base64():コンテンツを Base64 文字列に変換しますbase64(): Converts content to a base64 string
  • base64toString():Base64 でエンコードされた文字列を text/plain に変換しますbase64toString(): Converts a base64 encoded string to text/plain
  • base64toBinary():Base64 でエンコードされた文字列を application/octet-stream に変換しますbase64toBinary(): Converts a base64 encoded string to application/octet-stream
  • encodeDataUri():文字列を dataUri のバイト配列としてエンコードしますencodeDataUri(): Encodes a string as a dataUri byte array
  • decodeDataUri():dataUri をバイト配列にデコードしますdecodeDataUri(): Decodes a dataUri into a byte array

たとえば Content-Typeapplication/xml に設定された、次のような内容の HTTP 要求を受信したとします。For example, if you receive an HTTP request where Content-Type set to application/xml, such as this content:

<?xml version="1.0" encoding="UTF-8" ?>
<CustomerName>Frank</CustomerName>

このコンテンツは、xml() 関数と triggerBody() 関数から成る @xml(triggerBody()) 式を使ってキャストしてから、後で使用することができます。You can cast this content by using the @xml(triggerBody()) expression with the xml() and triggerBody() functions and then use this content later. または、xpath() 関数と xml() 関数を組み合わせた @xpath(xml(triggerBody()), '/CustomerName') 式を使用することもできます。Or, you can use the @xpath(xml(triggerBody()), '/CustomerName') expression with the xpath() and xml() functions.

他のコンテンツ タイプOther content types

その他のコンテンツ タイプについても Logic Apps で扱うことができ、サポートもされていますが、$content 変数をデコードすることによってメッセージ本文を手動で取得しなければならない場合があります。Logic Apps works with and supports other content types, but might require that you manually get the message body by decoding the $content variable.

たとえば、コンテンツ タイプが application/x-www-url-formencoded である要求によってロジック アプリがトリガーされるとします。For example, suppose your logic app gets triggered by a request with the application/x-www-url-formencoded content type. すべてのデータを維持するために、要求本文の $content 変数には、base64 文字列としてエンコードされたペイロードが含まれています。To preserve all the data, the $content variable in the request body has a payload that's encoded as a base64 string:

CustomerName=Frank&Address=123+Avenue

この要求はプレーン テキストでも JSON でもないので、アクションには次のように格納されます。Because the request isn't plain text or JSON, the request is stored in the action as follows:

"body": {
   "$content-type": "application/x-www-url-formencoded",
   "$content": "AAB1241BACDFA=="
}

Logic Apps には、形式データを処理するためのネイティブ関数が用意されています。以下に示したのは、その例です。Logic Apps provides native functions for handling form data, for example:

または次のような式を使って、データに手動でアクセスすることもできます。Or, you can manually access the data by using an expression such as this example:

@string(body('formdataAction'))

送信要求に同じ application/x-www-url-formencoded コンテンツ タイプ ヘッダーを適用したい場合は、@body('formdataAction') などの式を使って、その要求をアクション本体に追加すればよく、キャストは必要ありません。If you wanted the outgoing request to have the same application/x-www-url-formencoded content type header, you can add the request to the action's body without any casting by using an expression such as @body('formdataAction'). ただし、この方法が有効なのは、本体が body 入力内で唯一のパラメーターであるときのみです。However, this method only works when the body is the only parameter in the body input. application/json 要求内で @body('formdataAction') 式を使おうとすると、本体がエンコードされて送信されるためにランタイム エラーが発生します。If you try to use the @body('formdataAction') expression in an application/json request, you get a runtime error because the body is sent encoded.