PlatioPut - Platioへの出力

Platioアプリケーションのコレクションにレコードの作成・更新を行います。
Platioビルダーを使ってコレクション プロパティやフィールド定義を取得します。詳細についてはPlatioPutコンポーネント「Platioビルダーの使い方」を参照してください。

■ストリーム情報

入力フォーマットRecord,Text
接続数1
説明 Recordストリームを指定する場合は、入力ストリームのフィールド定義をPlatioビルダーで行います。
このフィールド定義は直前に連結したマッパーの出力ストリームのフィールド定義にコピーされ、そこに対して値のマッピングを行います。
マッピングする値の詳細については、下記トピック「Platioのフィールドへのマッピングについて」を参照してください。

Textストリームを指定する場合は、PlatioAPIの作成、更新用のJSON形式の文字列を渡します。
更新用のJSONには更新対象となるレコードのIDを含める必要があります。
例:レコードのID「rwq62qghjcveobpxgfcijp4b123」のレコードを更新するJSON
{
	"id": "rwq62qghjcveobpxgfcijp4b123",
	"values": {
		"c4b3de11": {
			"type": "String",
			"value": "infoteria"
		}
	}
}
				
JSONの形式については、Platio API リファレンス等を参照してください。
出力フォーマットRecord
説明 作成、更新したレコードを出力ストリームのフィールド定義に従ってレコード形式で出力します。
複数レコードあるRecordの入力ストリームで更新処理を行った場合、各Recordで対象となるPlatioのレコードが重なる場合があります。その場合同一のPlatioレコードが複数回出力されることになります。
例:$fromをフィールドに持つ2レコードの入力ストリームの場合
  • $from値:2017-07-27
  • $from値:2017-07-25
1レコード目の$from「2017-07-27」で、id「rwq62qghjcveobpxgfcijp4b123」が更新されたとします。
2レコード目の$from「2017-07-25」で、id「rwq62qghjcveobpxgfcijp4b123」、「abc74qgh45fd5bpxgfcijrqbhj8」の2レコードが更新されたとします。
この場合、出力ストリームは以下のように3レコードになります。
  • _RecordId値:rwq62qghjcveobpxgfcijp4b123
  • _RecordId値:abc74qgh45fd5bpxgfcijrqbhj8
  • _RecordId値:rwq62qghjcveobpxgfcijp4b123
出力されるストリームのレコードは処理の順になりますので、_RecordIdの順は前後する場合があります。

フィールド定義は指定したコレクション情報よりPlatioビルダーで作成します。
レコードのIDは_RecordIdという名前で出力します。

■コンポーネントプロパティ

名前プロパティ型マッピング説明
コネクションを使用boolean- 接続先に以下のコネクション名 を使用するかどうか選択します。
はい [true] - 以下のコネクション名 で指定されたPlatio接続名を接続先として使用します。
いいえ [false] - コネクション情報 以下のプロパティを使ってPlatioに接続を行います。
コネクション名connection-コネクションを使用 が「はい」の場合に、Platioアプリケーションへの接続用コネクションを指定します。
コネクションペインまたは管理コンソールにて作成した接続名を選択します。
コネクション情報group-コネクションを使用 プロパティが「いいえ」の場合に使用されるプロパティ群です。
アプリケーションベースURLstring入力&出力 PlatioのアプリケーションベースURLを指定します。
指定するURLは「 https://api.plat.io/v1/[アプリケーションのID] 」の形式で指定します。 コネクションを使用 が「いいえ」の場合にこの設定が参照されます。
トークンIDstring入力&出力 Platioの開発者向け情報ページから取得したAPIトークンのトークンIDを指定します。
詳細については下記トピック「APIトークンの取得方法」を参照してください。
コネクションを使用 が「いいえ」の場合にこの設定が参照されます。
秘密トークンpassword入力&出力 Platioの開発者向け情報ページから取得したAPIトークンの秘密トークンを指定します。
詳細については下記トピック「APIトークンの取得方法」を参照してください。
コネクションを使用 が「いいえ」の場合にこの設定が参照されます。
タイムアウトint入力&出力 Platioアプリケーションへの接続時のタイムアウト値を指定します。
コネクションを使用 が「いいえ」の場合にこの設定が参照されます。
プロキシ設定を使用boolean- 管理コンソールで設定したプロキシ設定を使用するかどうかを指定します。
コネクションを使用 が「いいえ」の場合にこの設定が参照されます。
はい [true] - プロキシ設定を使用します。
いいえ [false] - プロキシ設定を使用しません。
コレクションstring入力&出力 コレクションのIDかコレクションの名前を指定します。
Platioビルダーで選択することができます。
実行する処理choice-実行する処理を選択します。
追加 [Insert]
コレクションにレコードを登録します。
更新 [Update]
コレクションのレコードを更新します。更新対象のレコードが無い場合には、レコードが無い のエラーとなります。
更新/追加 [Upsert]
コレクションのレコードを更新もしくは登録します。更新対象のレコードが無い場合には新規にレコードが登録されます。
更新/追加(ユニークキー指定) [UpsertUKey]
キーとなるカラムを1つだけ指定してコレクションのレコードを更新します。更新対象のレコードが無い場合には新規にレコードが登録されます。
添付データ読込先string入力&出力 添付データを読み込むフォルダーを指定します。
相対パスの場合は、添付データ読込先パスの起点 の指定に基づいて解釈されます。
入力ストリームのフィールドで、Attachment型のフィールドへ「ファイル名」を指定すると、添付ファイルをレコードへ追加することができます。

例:以下の値を指定した場合
 添付データ読込先:「c:/temp/img」
 'Image'というAttachment型カラムへの値:「test.png」

Imageカラムへ「c:/temp/img/test.png」ファイルを添付します。

添付ファイルのContent-Typeは、指定しなければ自動で設定されます。 上記の場合「image/png」が設定されます。また、contentTypeへマッピングすることでContent-Typeを指定することもできます。
添付データ読込先パスの起点pathResolver入力&出力添付データ読込先 が相対パス指定の場合に、ベースフォルダーを指定します。

プロジェクトフォルダー [Relative]
プロジェクトファイルと同じフォルダーを起点にします。
ホームフォルダー [ProjectOwner]
プロジェクトオーナーのホームフォルダーを起点にします。
実行ユーザーのホームフォルダー [ExecuteUser]
実行ユーザーのホームフォルダーを起点にします。
区切り文字choice入力&出力 Array型のカラムに指定する値で、区切り文字として使用している文字列を指定します。
作成者string入力&出力 レコードの作成者をユーザー名もしくはユーザーIDで指定します。
指定した作成者は、添付ファイルをレコードへ追加する場合の添付ファイルの作成者としても使用されます。
指定しない場合の作成者は、APIトークンを生成したユーザーになります。
実行する処理」が「追加」、「更新/追加」で、各レコードごとに作成者を変更したい場合は、Platioビルダーのフィールド指定で「_Creator」フィールドを選択しレコードごとに作成者をマッピングします。
実行する処理」が「更新/追加」の場合、更新時に作成者は使用されません。
パラメーターcategory入力&出力 Platioアプリケーションへの接続時などに使用されるパラメーターを指定します。本プロパティは将来の拡張用のために存在し、基本的に使用することはありません。
コネクションを使用 が「いいえ」の場合にこの設定が参照されます。

■ループ処理

なし。

■トランザクション処理

コミット何もしません。
ロールバック何もしません。

■エラー処理

タイプパラメーターエラー処理フロー
へのストリーム
エラー
コード
説明
APIエラー「APIエラーのパラメーター 」
を参照してください。
コンポーネントの入力ストリーム1 Platio APIがエラーを返した場合
  • パラメーターが不正な場合
  • ユーザー認証に失敗した場合
  • リクエストが許可されていない場合
  • 幾つかのリソースが見つからない場合
  • リクエスト数の制限に達した場合
  • サーバー上で問題が発生した場合
  • 一時的にサービスを使用することができない場合
接続エラー なし コンポーネントの入力ストリーム2Platioとの通信中にエラーが発生した場合
3Platioとの通信中、もしくは通信前処理でエラーが発生した場合
レコードが無い なし コンポーネントの入力ストリーム4取得するレコードが無い場合
6指定したレコードIDの値が空の場合
参照先レコードが無い なし コンポーネントの入力ストリーム7参照先に指定したレコードが無い場合
汎用 なし コンポーネントの入力ストリーム5コネクション名 に指定したコネクションが見つからない場合
8ディレクトリの作成に失敗した場合
9Platioに関連するその他のエラーが発生した場合

■「APIエラー」のパラメーター

No.名前説明
1ErrorCodePlatio APIのエラーコードが返されます。
2StatusCodeHTTPのステータスコードが返されます。
3ErrorResponseエラーレスポンスのJSONが返されます。

■エラー処理フローへのストリームについて

エラー発生時に、コンポーネントがエラー処理フローへ渡すストリームは、基本的にコンポーネントの入力ストリームを使用します。ただし、レコードの作成・更新処理の途中でエラーが発生した場合で入力ストリームがRecordストリームの時は、入力ストリームの各レコードに次のような2つのフィールドを追加してエラー処理フローへ渡します。

フィールド名説明
_Statusレコードの処理状態が設定されます。
  • 成功(success)
  • 失敗(failure)
  • 未処理(unprocessed)

※各レコードの処理順は実行する処理で指定した処理により異なります。よって必ずしも失敗レコードの後続レコードが未処理となるわけではありません。
_ErrorMessageレコードの処理でエラーが発生した場合に、エラーメッセージが設定されます。

エラー処理フローへ渡されるストリームの例:

<?xml version="1.0" encoding="utf-8"?>
<RecordSet xmlns="http://www.infoteria.com/asteria/flowlibrary/record">
  <Record>
    <Field name="名前" type="String">AAA</Field>
    <Field name="アプリ1 番号" type="Decimal">1</Field>
    <Field name="アプリ1 名前" type="String">AAA</Field>
    <Field name="_Status" type="String">success</Field>
    <Field name="_ErrorMessage" type="String"></Field>
  </Record>
  <Record>
    <Field name="名前" type="String">BBB</Field>
    <Field name="アプリ1 番号" type="Decimal">999</Field>
    <Field name="アプリ1 名前" type="String">BBB</Field>
    <Field name="_Status" type="String">failure</Field>
    <Field name="_ErrorMessage" type="String">指定した参照先 [999] が存在していません。</Field>
  </Record>
  <Record>
    <Field name="名前" type="String">CCC</Field>
    <Field name="アプリ1 番号" type="Decimal">3</Field>
    <Field name="アプリ1 名前" type="String">CCC</Field>
    <Field name="_Status" type="String">unprocessed</Field>
    <Field name="_ErrorMessage" type="String"></Field>
  </Record>
</RecordSet>

■Platioのフィールドへのマッピングについて

Platioのカラム型とデータ型

Platioから取得した値、設定する値と、フィールド定義のデータ型の対応を以下に示します。

Platio型データ型
String型String
※複数行テキストのカラムに設定する場合の改行コードはLFを指定してください。
Number型Decimal
Boolean型Boolean
DateTime型DateTime
Date型String
Time型String
Location型
  • 緯度(latitude):Decimal
  • 経度(longitude):Decimal
  • 高度(altitude):Decimal
Attachment型
  • ID(id):String
  • 名前(name):String
  • 内容の形式(contentType):String
  • サイズ(size):Integer
User型
  • ID(id):String
  • 名前(name):String
Object型Object型に含まれるValueのタイプに合わせて設定されます。
Array型String
複数の値を区切り文字で繋げた値になります。
※Array型のvalueがObject型のような複雑なカラムを作成・更新する場合は入力ストリームにTextストリームのJSON文字列を使用する必要があります。
ReferenceString型String
参照先のレコードのカラムの値になります。
作成・更新する場合はカラム値を設定します。その値から検索して得られた1つ目のレコードのIDを参照先とします。
  • レコードID(recordId):String
    レコードIDを指定した場合、指定されたレコードを参照先とし値による検索は行われません。
ReferenceNumber型Decimal
参照先のレコードのカラムの値になります。
作成・更新する場合はカラム値を設定します。その値から検索して得られた1つ目のレコードのIDを参照先とします。
  • レコードID(recordId):String
    レコードIDを指定した場合、指定されたレコードを参照先とし値による検索は行われません。
ReferenceUser型String
参照先のレコードのカラムの値(名前、ID)になります。
作成・更新する場合は名前を設定します。その値から検索して得られた1つ目のレコードのIDを参照先とします。
  • レコードID(recordId):String
    レコードIDを指定した場合、指定されたレコードを参照先とし値による検索は行われません。

■APIトークンの取得方法

Platio APIを使用するためにはAPIトークンを生成する必要があり、PlatioPutコンポーネントは生成したAPIトークンを指定する必要があります。
APIトークンには「トークンID」と「秘密トークン」がありPlatioの「開発者向け情報」ページで生成することができます。
「トークンID」はAPIトークンを生成後、Platioの「開発者向け情報」ページよりいつでも確認することができますが、「秘密トークン」はAPIトークン生成時のみ表示され、その後、値を確認することはできません。
「秘密トークン」はAPIトークン生成時に「クリップボードにコピー」アイコンをクリックしてコピーし保存してください。

■Platio APIリクエスト回数

PlatioPutコンポーネントのPlatio APIリスエスト回数は以下のようになります。
API説明
レコードリスト・レコード・ユーザーリスト・アプリケーション定義の取得 更新する場合、更新対象のレコード件数100レコード(*1)ごとにリクエスト回数が増加します。
レコード内にUser型カラムがある場合、ユーザー情報を取得するため1回増加します。
レコード内にReferenceString型、ReferenceNumber型、ReferenceUser型カラムがある場合、カラム数×レコード数の回数増加します。
※ただし、User型、ReferenceString型、ReferenceNumber型、ReferenceUser型の値はコンポーネント内部で参照先の情報をキャッシュしていますので、同じレコードを参照している場合はリクエスト回数が減少することがあります。
(*1)Platioアプリケーションのデフォルトの最大値です。
レコードの作成・更新・削除 作成する場合は、100レコード(*1)ごとにリクエスト回数が増加します。
更新する場合は、処理するレコード数の回数リクエストします。「実行する処理」が「更新/追加(ユニークキー指定)」の場合は、100レコード(*1)ごとにリクエスト回数が増加します。
(*1)Platioアプリケーションのデフォルトの最大値です。
添付ファイルの作成 添付ファイル数の回数リクエストします。
※複数のレコードへ同じ添付ファイルを指定する場合もレコード数の回数リクエストします。
例:入力ストリーム1レコードでキー指定し、検索されたUser型カラム、Reference型カラムを持たないPlatioの1レコードを添付ファイル1つで更新の場合
「レコードリスト・レコード・ユーザーリスト・アプリケーション定義の取得」:2回
「レコードの作成・更新・削除」:1回
「添付ファイルの作成」:1回

例:入力ストリーム1レコードでレコードIDを指定しUser型カラム、Reference型カラムを持たないPlatioの1レコードを更新の場合
「レコードリスト・レコード・ユーザーリスト・アプリケーション定義の取得」:1回
「レコードの作成・更新・削除」:1回

※Platio APIは、Platioビルダー使用時にも使用されます。

■Platioビルダーの使い方

Platioビルダーは、コネクション名 で接続できるPlatioアプリケーションからコレクション一覧を取得し、そのコレクションのカラムを入力ストリーム、出力ストリームのフィールドとして設定する専用ツールです。

●Platioビルダーを起動する

以下のいずれかの操作でPlatioビルダーを起動します。

●コネクションの選択

コネクションを使用 で「はい」を設定し、コネクション名 が設定されていない場合、Platioビルダー起動時にコネクションダイアログが表示されます。
新規にコネクションを作成する場合は「新規コネクション」を選択してください。
既存のコネクションを使用する場合は「名前」のプルダウンリストより使用するコネクション名を選択してください。選択したコネクションを使用してPlatioアプリケーションへ接続します。

●新規コネクションの作成

「新規コネクション」を選択した場合「コネクションの作成」ダイアログが表示されますので、作成するコネクション名を入力し「OK」ボタンをクリックしてください。



コネクションのプロパティ入力するダイアログが表示されますので、コネクションの各プロパティを設定し「保存」ボタンをクリックしてください。

注意

この時点で新規コネクションが保存されます。

作成したコネクションでPlatioアプリケーションへ接続します。


Platioアプリケーションへの接続が成功すると以下のようなダイアログが表示されます。

●実行する処理を指定する

(1)の実行する処理プルダウンリストから実行する処理を選択します。

●作成または更新するレコードで使用するフィールドを指定する

(2)のコレクション一覧からコレクションを選択すると(3)に選択したコレクションから取得したフィールド一覧が表示されます。 フィールド一覧で選択チェックボックスをオンにします。指定したカラムを取り消すには、チェックボックスをオフにします。
実行する処理が「更新」、「更新/追加」の場合で、選択しないフィールドのカラムの値は更新されません。カラムの値を削除したい場合は、nullをマッピングする必要があります。

●更新時のキーにするフィールドを指定する

実行する処理が「更新」、「更新/追加」の場合は(3)のフィールド一覧でキーにするフィールドのキーのチェックボックスをオンにします。キーの指定を取り消すには、キーのチェックボックスをオフにします。
キーに指定されたフィールドの値で検索されたレコードを更新します。検索されたレコードが複数レコードの場合、それらすべてのレコードを更新します。
キーに指定できるフィールドには、Platioの「検索可能」なカラム以外に「_RecordId」「$from」「$to」「$fromTimestamp」「$toTimestamp」「$timezone」があります。キーに「$from」「$to」「$fromTimestamp」「$toTimestamp」を指定した場合、直前のマッパーでは検索で使用する日時の文字列をマッピングします。日時の文字列にミリ秒を含めたい場合は、YYYY-MM-DD'T'HH:mm:ss.SSS'Z'形式の日時の文字列をマッピングします。この場合、タイムゾーンはUTCとなります。
例:「$from」の値に「2017-01-13」を設定した場合
 検索条件「$from:2017-01-13」でレコードの更新時刻による検索を指定することになります。
「$timezone」は「$from」「$to」「$fromTimestamp」「$toTimestamp」を指定した場合にUTC以外のタイムゾーンを指定したい場合に使用します。

キーに「_RecordId」を指定した場合、対象のレコードが1つ特定されますので、他のキー指定は無視されます。

●取得条件オプション

Arrayセパレーターを指定もしくは入力する

Array型のセパレーターをプルダウンリストから選択します。

他の文字列をセパレーターとして使用したい場合は、文字列を入力します。