マルチパートリクエスト

マルチパートリクエストは、複数のデータセットを境界で区切って単一のボディに結合します。通常、これらのリクエストはファイルアップロードや、単一のリクエストで複数の種類のデータ（例：ファイルとJSONオブジェクト）を転送するために使用されます。OpenAPI 3では、マルチパートリクエストを次のように記述します。

1
requestBody:
2
  content:
3
    multipart/form-data: # Media type
4
      schema: # Request payload
5
        type: object
6
        properties: # Request parts
7
          id: # Part 1 (string value)
8
            type: string
9
            format: uuid
10
          address: # Part2 (object)
11
            type: object
12
            properties:
13
              street:
14
                type: string
15
              city:
16
                type: string
17
          profileImage: # Part 3 (an image)
18
            type: string
19
            format: binary

requestBody/contentキーワードから始めます。次に、リクエストデータのメディアタイプを指定します。ファイルアップロードでは通常_multipart/form-data_メディアタイプを使用し、混合データリクエストでは通常_multipart/mixed_を使用します。メディアタイプの下にschemaキーワードを置き、リクエストペイロードの記述を開始することを示します。リクエストの個々の部分は、schemaオブジェクトのプロパティとして記述します。ご覧のとおり、マルチパートリクエストには、文字列、JSON形式のオブジェクト、バイナリデータなど、さまざまなデータを含めることができます。また、アップロード用に1つまたは複数のファイルを指定することもできます。（詳細については、「ファイルアップロード」を参照してください。）上記の例は、次のリクエストに対応しています。

1
POST /upload HTTP/1.1
2
Content-Length: 428
3
Content-Type: multipart/form-data; boundary=abcde12345
4

5
--abcde12345
6
Content-Disposition: form-data; name="id"
7
Content-Type: text/plain
8

9
123e4567-e89b-12d3-a456-426655440000
10
--abcde12345
11
Content-Disposition: form-data; name="address"
12
Content-Type: application/json
13

14
{
15
  "street": "3, Garden St",
16
  "city": "Hillsbery, UT"
17
}
18
--abcde12345
19
Content-Disposition: form-data; name="profileImage "; filename="image1.png"
20
Content-Type: application/octet-stream
21

22
{…file content…}
23
--abcde12345--

Content-Typeの指定

デフォルトでは、個々のリクエストパートのContent-Typeは、リクエストパートを記述するschemaプロパティのタイプに応じて自動的に設定されます。

スキーマプロパティタイプ

Content-Type

プリミティブまたはプリミティブの配列

text/plain

複合値または複合値の配列

application/json

binaryまたはbase64形式の文字列

application/octet-stream

リクエストパートに特定のContent-Typeを設定するには、encoding/_{property-name}_/contentTypeフィールドを使用します。encodingは、schemaと同じレベルでメディアタイププロパティの子として追加します。以下の例では、マルチパートリクエストのprofileImageパートのcontentTypeをimage/png, image/jpgに設定しています。

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties: # Request parts
7
          id:
8
            type: string
9
            format: uuid
10
          address:
11
            type: object
12
            properties:
13
              street:
14
                type: string
15
              city:
16
                type: string
17
          profileImage:
18
            type: string
19
            format: base64
20
      encoding: # The same level as schema
21
        profileImage: # Property name (see above)
22
          contentType: image/png, image/jpeg

カスタムヘッダーの指定

マルチパートリクエストのパートは通常、Content以外のヘッダーを使用しません。カスタムヘッダーを含める必要がある場合は、encoding/_{property-name}_/headersフィールドを使用してこれらのヘッダーを記述します（以下を参照）。ヘッダーの記述に関する完全な情報については、「パラメーターの記述」を参照してください。以下は、マルチパートリクエストの一部に定義されたカスタムヘッダーの例です。

1
requestBody:
2
  content:
3
    multipart/form-data:
4
      schema:
5
        type: object
6
        properties:
7
          id:
8
            type: string
9
            format: uuid
10
          profileImage:
11
            type: string
12
            format: binary
13
      encoding:
14
        profileImage: # Property name
15
          contentType: image/png, image/jpeg
16
          headers: # Custom headers
17
            X-Custom-Header:
18
              description: This is a custom header
19
              schema:
20
                type: string

この宣言は、次のリクエストと一致します。

1
POST /upload HTTP/1.1
2
Content-Length: 428
3
Content-Type: multipart/form-data; boundary=abcde12345
4

5
--abcde12345
6
Content-Disposition: form-data; name="id"
7
Content-Type: text/plain
8

9
123e4567-e89b-12d3-a456-426655440000
10
--abcde12345
11
Content-Disposition: form-data; name="profileImage"; filename="image1.png"
12
Content-Type: image/png
13
X-Custom-Header: x-header
14

15
{…file content…}
16
--abcde12345--

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください