ホーム > ドキュメント  > バイナリデータ API の利用方法

バイナリデータ API の利用方法

『奉行クラウド』で、画像ファイルなどのバイナリデータを処理する API は、バイナリデータのアップロード／ダウンロードする API と、バイナリデータと関連付けるデータ登録／取得 API が対になっています。
アップロードとダウンロードで処理フローが異なるため、それぞれの利用方法をご確認ください。
詳細は、API ごとのリファレンスをご参照ください。

バイナリデータのアップロード

奉行クラウド API では、バイナリデータをアップロードし、そのバイナリデータと関連付けるデータを登録することで、『奉行クラウド』で利用できるデータにします。

Upload API を使用したバイナリデータのアップロード

Upload API は、バイナリデータをアップロードする API です。
Upload API を呼び出すと、アップロードしたバイナリデータごとに、一時的な Key となる「fileKey」がレスポンスとして返却されます。
この Key を使用して関連付けをします。

リクエストの形式

Upload API は Content-Type を multipart/form-data として、バイナリデータをアップロードします。
例えば、PDF ファイルをアップロードする場合、ファイル名や拡張子のファイルの情報と、バイナリデータを合わせて1回の API 呼び出しでアップロードします。

Upload API のリクエストのサンプルを記載します。
1つ目のブロックは、Content-Type を「application/json」にして、ファイル情報を指定しています。
2つ目のブロックは、Content-Type を「application/pdf」にして、PDFファイルのバイナリデータを指定しています。

Request

POST https://api-sandbox.obc.jp/hm/UploadXXXX
Authorization: Bearer ****************************** 
X-OBC-SubscriptionKey: ****************************** 
X-OBC-TenantID: *********** 
Content-Type: multipart/form-data; boundary=[boundary]

--[boundary] 
Content-Disposition: form-data; name="fileInfo"; 
Content-Type: application/json 

{ 
    fileName: "XXXX.pdf", 
    extension: "pdf" 
} 
--[boundary] 
Content-Disposition: form-data; name="file"; 
Content-Type: application/pdf

ファイルのバイナリデータ 
--[boundary]--

boundary 文字列

boundary 文字列は、リクエストボディに指定した複数のデータを区切る「境界区切り文字」と呼ばれる文字列です。

参考
・ ASCII 文字の70文字以内で定義できます。
・データ内の文字列と重複できません。
・境界区切りの行は、2つの「-」（ハイフン）とリクエストヘッダーに定義した boundary の値で構成されます。
・最後に続く境界区切りの線は、boundary 文字列の最後に「-」（ハイフン）が2つ追加されます。

データ登録 API を使用したバイナリデータとの関連付け情報の登録

『奉行クラウド』で利用できるデータにするために、バイナリデータをアップロードした後、バイナリデータと関連付けるデータを登録します。
データの関連付けは、Upload APIのレスポンスで取得した「fileKey」を使用します。

Upload API の利用方法

バイナリデータをアップロードして、『奉行クラウド』で利用できるデータにするまでの一連のフローです。

Request

POST https://api-sandbox.obc.jp/hm/UploadXXXX 
Authorization: Bearer ****************************** 
X-OBC-SubscriptionKey: ****************************** 
X-OBC-TenantID: *********** 
Content-Type: multipart/form-data; boundary=[boundary] 

--[boundary] Content-Disposition: form-data; name="fileInfo"; 
Content-Type: application/json
 
{ 
    fileName: "XXXX.jpg", 
    extension: "jpg" 
}
 
--[boundary] 
Content-Disposition: form-data; name="file"; 
Content-Type: image/jpg
 
ファイルのバイナリデータ 
--[boundary]--

Response Body

{
    "fileKey": "********************************", 
}

「fileKey」は、アップロードしたバイナリデータを識別する一時的な Key です。

Request（社員情報の受入：ImportEmployee）

POST https://api-sandbox.obc.jp/hm/XXXX 
Authorization: Bearer ****************************** 
X-OBC-SubscriptionKey: ****************************** 
X-OBC-TenantID: *********** 
Content-Type: application/json; charset=utf-8 
{ 
    "dataList": [ 
        { 
            "HM3010001": "100000", 
            "HM3010003": "山田　一朗", 
            "HM3010011": "1987/04/01", 
            "HM3011405": "2.0", 
            "HM3010007_F": "********************************"
        } 
    ] 
}

リクエストボディに「fileKey」を指定し、「1. Upload API の実行」でアップロードしたバイナリデータと関連付けるデータを登録します。
ステータスコード：200 が返却されたら、登録は完了です。

Upload API の注意事項

Upload API でアップロードしたバイナリデータは、データ登録 API によって関連付けされない場合、3日間で自動的に削除されます。
削除された場合は、再度バイナリデータをアップロードする必要があります。
バイナリデータに関連する API のレート・クォータ制限もご参照ください。

バイナリデータのダウンロード

奉行クラウド API では、バイナリデータと関連付けたデータを取得し、そのデータに含まれる「fileKey」を使用して、バイナリデータをダウンロードできます。

Export API を使用したバイナリデータの関連付け情報の取得

Export API は、バイナリデータと関連付けたデータを取得する API です。
バイナリデータごとに、一時的な Key となる「fileKey」がレスポンスとして返却されます。
この Key を利用して、Download API を実行します。

Download API を使用したバイナリデータのダウンロード

Download API は、バイナリデータをダウンロードする API です。
Export API のレスポンスで取得した「fileKey」をリクエストボディに指定します。

Download API の利用方法

バイナリデータをダウンロードするまでの一連のフローです。

Response Body（社員情報の取得：ExportEmployee）

[
    {
        "HM3010003": 
        "山田　一朗", 
        "HM3010011": "1987/04/01", 
        "HM3011405": "2.0", 
        "HM3010007_F": "********************************" 
    }, 
    {
        "HM3010003": "川谷　しげる", 
        "HM3010011": "1986/04/01",
        "HM3011405": "36.0",
        "HM3010007_F": "********************************"
    }
]

Request

POST https://api-sandbox.obc.jp/hm/DownloadXXXX 
Authorization: Bearer ****************************** 
X-OBC-SubscriptionKey: ****************************** 
X-OBC-TenantID: *********** 
Content-Type: application/json; charset=utf-8 
{ 
    "fileKey": "********************************" 
}

リクエストボディに「fileKey」を指定します。

Response Header

Content-Type: application/octet-stream 
Content-Disposition: attachment; filename={ファイル名}

レスポンスヘッダーには、上記の値が設定され返却されます。
「filename」には、ファイル名が設定されます。
ステータスコード：200 でバイナリデータが返却されたら、ダウンロードの完了です。

非 ASCII 文字（ひらがな・カタカナ・漢字など）が含まれたファイルをダウンロードする場合、「filename」には MIME エンコード（UTF-8 の文字セットで Base64 でエンコード）された文字列が設定されます。

Content-Type: application/octet-stream 
Content-Disposition: attachment; filename={=?文字セット?エンコード方式?エンコードされたファイル名?=}

Download API の注意事項

Export API で取得した「fileKey」の有効期間は1日です。
1日以上経過してから Download API を実行する際、「fileKey」が無効になっているため、再度「fileKey」を取得する必要があります。
バイナリデータに関連する API のレート・クォータ制限もご参照ください。