コールバック基本情報を定義しよう

クエスト概要

「アウトプット・インプットの連携方式を定義しよう」のクエストで、「連携結果を返却する」を選択し、返却先の連携方式を定義した場合にこのクエストは解放されます。
連携先システムへの出力結果を連携元システムに連携するため、事前に指定した連携方式に従って、コールバックのためのより詳細な要件を定義します。 このクエストは、インプット/アウトプット基本情報を定義しよう、と基本的な構成は同じです。 コールバック基本情報も、アウトプット、インプットの基本情報と同様に、指定した連携方式に従って定義するため、以下の内、どちらの連携方式を指定するかによって定義する内容は変わります。

• ファイルストレージサービス、またはプロトコル - ファイル(FTPS・SFTP)
• クラウドアプリケーション、またはプロトコル - WEBAPI(HTTP・HTTPS)
  ※連携方式が「クラウドアプリケーション・プロトコル - WEBAPI(HTTP・HTTPS)」の場合、APIリファレンスを元に定義する必要があるため、連携システムのご担当者様にお問い合わせの上、事前にAPIリファレンスを準備して下さい。

---

用語一覧

このクエストで登場する用語を解説します。
以下、どちらの連携方式を指定するかによって定義する内容は変わります。

• ファイルストレージサービス、またはプロトコル - ファイル(FTPS・SFTP)
• クラウドアプリケーション、またはプロトコル - WEBAPI(HTTP・HTTPS)

---

コールバック処理の実行対象のインプットデータ

コールバック処理を実行する対象は、以下の中から該当するものをチェックをつけてください。チェックをつけたものだけ実行されます。 インプットが複数ある場合は、軸となるインプットと指定されたものだけ実行されます。

• 連携成功した行
  データ連携が正常終了したレコードに対してコールバックをします。

• 連携失敗した行
  データ連携が異常終了したレコードに対してコールバックをします。

• 他のエラー行により処理がスキップされた行
  エラー時連携処理仕様で、エラーが発生した場合にスキップする、としていた場合にスキップされたレコードに対してコールバックをします。

• フィルタされた行
  インプットフィルターリレーション定義で、フィルタされた行に対してコールバックをします。

---

連携方式で「ファイルストレージサービス」、または「プロトコル - ファイル(FTPS・SFTP)」を選択した場合

ファイル形式

連携先システムに出力するファイルの形式を選択します。以下の情報を参考に適したものを選択して下さい。

• csv/tsv
  カンマ区切り/タブ区切りのファイル
• json
  JavaScriptのオブジェクトの書き方を元にしたファイルで、WebAPIのデータ交換フォーマット
• ファイル
  連携元システムからPDFや画像等のバイナリデータを送信したい場合に選択

出力先フォルダパス

記載例を参考に、連携先システムに出力するファイルを配置するフォルダの場所を定義します。
S3の連携方式の場合はバケット名は含まないように定義してください。bucketなどの環境情報は別のクエストで定義します。
また出力先フォルダパスは、フォルダの最後には/が入るように定義して下さい。
記載例：output/sampleif001/

出力ファイル名

連携先システムに変換後のデータとして実際に出力するファイル名となります。拡張子込みで記載して下さい。
ここで定義されたファイル名で連携先システムには送信されます。ファイル名に利用できる動的文字列は以下が利用可能です。利用する場合は${yyyyMMdd}のように${}でくくって定義してください。
利用可能な動的文字列：
年：yyyy　月：MM　日：dd　時：hh　分：mm　秒：ss　
記載例：
output_sample${yyyyMMdd}.csv ⇒ output_sample20230612.csv
${yyyy}${MM}output_sample${ddhhmm}.csv ⇒ 202306output_sample162316.csv

文字コード

文字コードとは、連携するファイルの文字コードを定義します。 連携されるデータの文字コードがSJISなのに、ここの定義でUTF-8としてしまうと連携するデータが文字化けしたりする可能性があります。
サンプルの連携データがある場合はテキストエディタで開けば文字コードを確認することも可能ですし、WEBAPIで連携するデータであれば、基本的にはそのシステムの文字コードと同様かと思いますので、 分からない場合はシステムのご担当者様にご確認ください。

出力ファイル配置先ディレクトリに同名ファイルが存在した場合

出力ファイル配置先ディレクトリに同名のファイルがあった場合、taiasでは以下二つのふるまいを選択できます。連携先のシステムの仕様に合わせて選択して下さい。
・もともと存在していたファイルを削除して新しいファイルが配置します
・同じファイル名が存在していた場合、タイムスタンプがついたファイル名となってファイルが配置されます

---

以下内容はファイル形式がCSV/TSVの場合のみ定義します

区切り文字

「区切り文字」とは、アウトプットファイル内のデータをテキストファイル形式で保存する際に、項目（フィールド）を区切る記号として使用される文字のことです。 taiasでは区切り文字として、csvファイルで利用されるカンマや、tsvファイルで利用されるタブ、半角スペースをサポートしています。
連携先のシステムの取込仕様に合わせて、アウトプットとして出力されるファイルの「区切り文字」を選択しましょう。

ヘッダー行の有無

ヘッダー行の有無は、CSVファイルの中身に、カラム情報となるヘッダ行が含まれるか否かを定義します。 CSVファイルの1行目からデータとして扱うか、1行目はヘッダ行として2行目からデータ行として扱うかの違いとなります。 ヘッダ有にすればヘッダー付きのアウトプットファイルが、ヘッダ無しにすればヘッダーなしのファイルが作成されます。 連携先のシステムの取込仕様に合わせて、アウトプットとして出力されるファイルの「ヘッダー行の有無」を選択しましょう。

くくり文字

くくり文字は、CSVのデータが「"aaa","bbb"」のようになっている場合の「"」を指し、区切り文字として指定したカンマやタブを文字情報として出力したい場合に、利用します。
例えば「このリンゴは10個で1,500円です」という文字列情報を普通にCSVファイルとして解釈した場合、
「このリンゴは10個で1」と「500円です」に項目が分かれてしまいます。
これを回避するために「”このリンゴは10個で1,500円です”」と両端にくくり文字を入れることで、区切り文字を含んだ一連の文章を文字情報としてシステムが認識できるようになります。 taiasでは、半角ダブルクォーテーション「”」や半角クォーテーション「’」の「くくり文字」をサポートしています。
連携先のシステムの取込仕様に合わせて「くくり文字」を選択しましょう。くくり文字が不要であれば「なし」を選択して下さい。

改行コード

「改行コード」とは、ファイル内で文書が改行することを指示するコードです。 OSによって異なり、WindowsではCR＋LFが利用されることが一般的です。
連携先のシステムの取込仕様に合わせて「改行コード」を選択しましょう。taiasでは、「CR＋LF」「CR」「LF」の「改行コード」をサポートしています。

BOMの付与

BOMとは「byte order mark(バイト順マーク)」の略称でUnicodeの符号化形式で符号化したテキストの先頭につける数バイトのデータのことです。BOMをファイルの先頭につけるかどうかを指定できます。
文字コードUTF-8でファイル出力し、Excelで開く場合、BOMがついていないと上手くファイルが開けないことがあります。

エスケープ文字

「エスケープ文字」とは、くくり文字そのものを記載したいときに、くくり文字の直前に使用する文字です。
例えばダブルクオテーションマーク「"」そのものを表現したい時は、「"」の直前にエスケープ文字をいれます。
この時エスケープ文字として「\」を入れる場合は「\"」、「/」を入れる場合は「/"」と記載します。
連携先のシステムの取込仕様に合わせて「エスケープ文字」を定義しましょう。

---

連携方式で「クラウドアプリケーション」、または「プロトコル - WEBAPI(HTTP・HTTPS)」を選択した場合

プロトコル

プロトコルとは、Webサーバーと通信するための通信規則を指し、HTTPSとHTTPの違いは、通信が暗号化されるか否かの違いです。 暗号化されていれば「HTTPS」、暗号化されていなければ「HTTP」です。I/Fで連携するデータは基本的にはセキュアになっている必要があると思いますので特別な事情がない限りはHTTPSにすべきです。HTTPSにはSSLサーバー証明書が必要です。 連携したいシステムへのURLがhttpから始まればHTTPをhttpsから始まるのであればHTTPSとなります。
例：
http://taias-sample.com/ →HTTP
https://taias-sample.com/ →HTTPS

フォーマット形式

連携先システムに出力するファイルの形式を選択します。以下の情報を参考に適したものを選択して下さい。
利用したいAPIが何なのか判断できない、APIリファレンスがどこにあるのか分からない、という場合は連携システムのご担当者様に問い合わせて下さい。

• application/json
  json形式で送りたい場合
• text/csv
  csv(tsv)形式で送りたい場合
• application/x-www-form-urlencoded
  キー、値のFormDataとして送信する場合
• multipart/form-data
  キー、値（ファイル含む）を複数のContent-Typeのデータとして送信する場合。
  WEBAPIでファイルを送信する場合、こちらを使うのが一般的です。
  

HTTPリクエストメソッド

HTTPリクエストメソッドとは、フォーマット形式と同様にWEBAPIのリクエストにのせるものの1つで、リクエスト先に対してどのような処理をお願いするのか、を示すものとなります。POSTは登録、PUTは更新、というように一般的には決まっていますが、必ずしもそうなっていないAPIは多数ありますので、APIリファレンスを確認して定義するようにしてください。
（連携用のWEBAPIが用意されているのであれば、仕様書にはHTTPリクエストメソッドは明記されていると思いますのでご確認ください。 仕様書もない、という場合は連携システムのご担当者様に、「I/Fで連携するWEBAPIのHTTPリクエストメソッドは、POST,PUT,PATCHのいずれになるか」とご確認ください）

URLパス

URLパスではURLの内のプロトコルとホスト（ドメイン）以下のパスを定義します。
APIリファレンスでは、「endpoint(エンドポイント)」という記載がされているケースも多いです。
taiasでは環境毎にI/F定義をしないで済むように、環境依存情報は切り出して定義することができるようにしています。
そのためここでは環境に依存しない部分のURLのパスを定義します。
例：
(1) APIのURLが「https://taias-sample.com/sample/if-data/」 の場合
URLパスは「sample/if-data/」となります。

また、URLパスには、URLの一部に{}を用いて変数として定義することができます。変数を用いることで、URLの一部に日付を入れたい、入力リソースの値を動的に入れたい、ということが可能になります。ここでURLパスに{}を用いたURLを定義した場合、{}の変数に対して、後続のクエストのマッピングで具体的にどういう値にするのか設定します。

例：更新するAPIのURLに対して、入力データのcodeを動的に利用したい場合
URLパス：https://taias-sample.com/sample/{code}
↓
後続クエストのマッピング定義にて、{code}に対して、インプットのデータをマッピング定義することで、 連携するレコード毎にURLを変更することができます。

文字コード

文字コードとは、連携するファイルの文字コードを定義します。
連携されるデータの文字コードがSJISなのに、ここの定義でUTF-8としてしまうと連携するデータが文字化けしたりする可能性があります。
サンプルの連携データがある場合はテキストエディタで開けば文字コードを確認することも可能ですし、WEBAPIで連携するデータであれば、基本的にはそのシステムの文字コードと同様かと思います。文字コードについてはAPIリファレンスに明記されていないこともあり、その場合はUTF-8であることが多いですが、分からない場合はシステムのご担当者様にご確認ください。

出力先へのレコード数上限

連携先システムへ出力するアウトプットファイルのレコード数の上限件数を指定するかどうかを選択します。
1ファイルあたりのサイズを一定に抑える必要がある場合や、1回の連携で大量のデータを連携する場合に、連携先のシステムの仕様に合わせて適したものを選択して下さい。
API連携の場合も、連携システムによっては一度のリクエストで送信可能なデータ件数に制限がある場合があり、 そういった場合にはこの定義を「指定する」とすることで分割して送信することができます。 何件でも受け付けられるAPIや、一度の連携処理でその上限になることはありえない、という場合は「指定しない」とします。分からない場合は連携システムのご担当者様にご確認ください。

上限レコード数

出力先へのレコード数上限を指定する場合は、その上限レコード数も合わせて定義します。 ここで指定したレコード数でリクエストを分割して繰り返し送信することができます。
1回のリクエストのレコード数上限については、通常APIリファレンスに記載されているかと思いますが、分からない場合は連携システムのご担当者様にご確認ください。

リクエストヘッダパラメータ

リクエストヘッダは、WebAPIにリクエストを送る際に、HTTPリクエストに含める情報のことです。
ブラウザの種類やバージョン、言語、リクエストがどのページから来たか、クッキー情報などが含まれます。
ここではAPI毎にHTTPリクエストを投げる際のリクエストヘッダパラメータを定義します。 リクエストヘッダは、トークンの指定が必要なケースがありますが、トークン自体はテスト環境と本番環境など、接続する環境毎に異なる値になります。ですので、I/F定義で定義するリクエストヘッダは、APIリファレンスに記載されている指定が必要なリクエストヘッダパラメータから、環境に依存せずに決められるものだけを定義するようにしてください。

---

関連リンク

このクエストに関連する機能仕様、FAQのリンクです。
・ 機能仕様
・ FAQ