<feed>
<entry>
  <contributor>
    <email>foo.bar@vte.cx</email>
  </contributor>
  <id>/_user/216,2</id>
  <link href="/_user/216" rel="self" />
  <summary>Activated</summary>
  <title>foobar@vte.cx</title>
  <subtitle>nickname</subtitle>
  <published>2018-06-09T11:08:38.122+09:00</published>
  <updated>2018-06-09T13:38:15.360+09:00</updated>
</entry>
</feed>

ユーザステータスには以下の種類があります。

• 登録なし: Nothing
• 仮登録：Interim
• 本登録：Activated
• 無効：Revoked
• 退会：Cancelled

ユーザ登録画面から仮登録を実行するとステータスがInterimになりユーザに確認メールが送信されます。メール内のリンクをクリックすることで本人認証がなされステータスが本登録(Activated)に変わります。Activatedになることではじめてサービスを使うことができるようになります。
また、ユーザ管理者によってユーザを追加することもできます。詳しくは、「管理者によるユーザ登録」を参照してください。
ユーザ管理者は PUT /d/?_revokeuser={ユーザアカウント}を実行することでアカウントを一時的に無効(Revokded)にすることができます。有効にするには、PUT /d/?_activateuser={ユーザアカウント}を実行します。
また、DELETE /d/?_canceluserで、ログインユーザのステータスを「Cancelled」(退会)に変更できます。これは、ログインユーザ自身のみ実行可能です。

uid検索

GET /d/?_uidを実行するとログイン中のuidを返却します。戻り値にはfeedのtitleにuidがセットされます。ログインしていない場合、HTTPステータス401を返却します。

ユーザアカウント検索

GET /d/?_accountを実行するとログイン中のユーザアカウントを返却します。戻り値にはfeedのtitleにユーザアカウントがセットされます。ログインしていない場合はHTTPステータス401を返却します。

ログインとログアウト

ログイン画面からログインIDとパスワードを入力して実行することでログイン認証が行われセッションを開始します。このとき、ログイン画面からはGET /d/?_loginが実行されます。また、パスワードはハッシュ化され、ワンタイムトークン(WSSE)としてリクエストされます。２回のログイン認証に失敗するとreCAPTCHAによる認証が必要になります。ログインロジックの詳細については、vtecxblankプロジェクトのログイン画面のソースを参照してください。ユーザアプリケーション作成の際にはこのログイン画面をカストマイズするとよいでしょう。
GET /d/?_logoutが実行されるとログアウトされセッションが破棄されます。

ユーザ仮登録

ユーザ仮登録はPOST /d/?_adduserで以下のエントリを登録すると実行されます。
機械的に実行されることを防ぐためreCAPTCHAが要求されます。

<feed>
  <entry>
    <contributor>
      <uri>urn:vte.cx:auth:{ユーザアカウント},{パスワード}</uri>
      <name>{ニックネーム}</name>
    </contributor>
    <title>{メールのタイトル(省略可)}</title>
    <summary>
    {テキストメール本文(省略可)}
    </summary>
    <content>
   {HTMLメール本文(省略可)}
    </content>
  </entry>   
</feed>

上記を実行すると、summaryタグもしくは、contentタグに記述された文章とタイトル(titleタグ)がメール送信されます。contentにはHTMLメール(任意)を、summaryにはテキストメール(必須)を記述してください。HTMLメールを表示できない場合はテキストメールになります。
メール送信内容は、以下のように /_settings/adduserエントリにも記述できます。上記エントリのsummary、content、titleが省略された場合は、/_settings/adduserエントリの内容でメール送信します。上記エントリのメール送信内容が存在せず、かつ、/_settings/adduserエントリーも存在しない場合、?_adduserがリクエストされるとHTTPステータス412(Precondition Failed)が返ります。
また、メール送信するには、 /_settings/propertiesにメール送信設定が記述されている必要があります。詳しくは、各種設定情報の「プロパティ情報」を参照してください。

<entry>
  <link rel="self" href="/_settings/adduser" />
  <title>{メールのタイトル}</title>
  <summary>
{テキストメール本文}
  </summary>
  <content>
{HTMLメール本文}
</content>
</entry>

メールの本文には、ワンタイムトークン(RXID)が付いたリンクを含む必要があります。メールの本文に${RXID=Key}を挿入することで、RXIDを含むURLが自動的に組み立てられます。ユーザがこのリンクをクリックするまでは仮登録となります。

初期フォルダ作成

　また、以下のようにadduserinfoエントリのsummaryタグにフォルダのキーを設定することで、最初にログインしたタイミングで自動的にフォルダが作成されます。
キー情報の"#"部分は登録時のユーザ(uid)で置換されます。

<entry>
  <link rel="self" href="/_settings/adduserinfo" />
  <summary>
{ユーザ登録時に作成するフォルダのキー}
/#/aaaa
/#/bbbb
....
  </summary>
</entry>

vtecxblankプロジェクトには、ユーザ仮登録の画面が用意されています。ユーザアプリケーション作成の際にはこの画面をカストマイズするとよいでしょう。

パスワードリセット

パスワードリセットはPOST /d/?_passresetで以下のエントリを登録することで実行されます。機械的に実行されることを防ぐためreCAPTCHAが要求されます。

<feed>
  <entry>
    <contributor>
      <uri>urn:vte.cx:auth:{ユーザアカウント}</uri>
    </contributor>
    <title>{メールのタイトル(省略可)}</title>
    <summary>
    {テキストメール本文(省略可)}
    </summary>
    <content>
   {HTMLメール本文(省略可)}
    </content>
  </entry>
</feed>

上記を実行すると、summaryタグ(テキストメール)もしくは、contentタグ(HTMLメール)に記述された文章がメール送信されます。メール送信内容は、以下のように/_settings/passresetエントリにも記述できます。上記エントリのsummary、content、titleが省略された場合は、/_settings/passresetエントリの内容でメール送信します。
メールにはワンタイムトークン(RXID)リンクを含む必要があります。
ユーザがこのリンクをクリックすることでパスワードを再設定します。
上記エントリにメール送信情報がなく、 /_settings/passresetエントリーにも存在しない場合、?_passresetがリクエストされるとHTTPステータス412(Precondition Failed)が返ります。

　vtecxblankプロジェクトには、パスワードリセットの画面が用意されています。ユーザアプリケーション作成の際にはこの画面をカストマイズするとよいでしょう。

パスワード変更

パスワード変更はPUT /d/?_changephashで以下のエントリを更新することで実行されます。ログイン中のアカウントに対して実行するため、reCAPTCHAは要求されません。

<feed>
  <entry>
    <contributor>
      <uri>urn:vte.cx:auth:,{パスワード}</uri>
    </contributor>
  </entry>
</feed>

vtecxblankプロジェクトには、パスワード変更の画面が用意されています。ユーザアプリケーション作成の際にはこの画面をカストマイズするとよいでしょう。

管理者によるユーザ登録

?_adduserByAdminパラメータを付けて以下を実行することで新規ユーザを登録します。

• これはユーザ管理者のみが実行できます。
• 複数のエントリを指定することで同時に複数のユーザを登録できます。
• 本人認証（メールリンクをクリック）しなくても本登録になります。
• ユーザ登録時に/_settings/adduserinfoに設定した初期フォルダが作成されます。
• titleタグおよびsummary、contentにメール情報をセットすることで実行時にメールを送信することができます。
  • ただし、メール送信のための設定が/_settings/propertiesエントリに記述されている必要があります。詳しくは、各種設定情報の「プロパティ情報」を参照してください。
• titleタグおよびsummary、contentが省略されており、かつ、/_settings/adduserByAdminエントリが登録されている場合、このエントリの内容でメールが送信されます。

POST|PUT /d?_adduserByAdmin

<feed>
   <entry>
     <contributor>
       <uri>urn:vte.cx:auth:{メールアドレス},{パスワード}</uri>
       <name>{ニックネーム}</name>
     </contributor>
     <title>メールのタイトル(任意)</title>
     <summary>テキストメール本文(任意)</summary>
     <content>HTMLメール本文(任意)</content>
   </entry>

   ...
 </feed>

管理者によるパスワード変更

?_changephashByAdminパラメータを付けて以下を実行することでパスワードを変更します。

• これはユーザ管理者のみが実行できます。
• ?_adduserByAdminで作成されたユーザのパスワードのみ変更できます。
• リクエストデータに対象UIDとパスワードを指定します。指定したUIDのユーザのパスワードが更新されます。

PUT /d?_changephashByAdmin

<feed>
<entry>
<contributor>
<uri>urn:vte.cx:auth:,{パスワード}</uri>
</contributor>
<link href="/_user/{UID}/auth" rel="self" />
</entry>

...
</feed>

アカウント変更

PUT /d?_changeaccountでアカウント変更のためのメール送信を行います。これはログインユーザ自身のみ実行可能です。

• メールのタイトルと本文についてリクエストに指定されていればそれを使用し、指定されていなければ/_settings/changeaccountエントリーの設定内容を送信します。
• 実際にアカウントを更新する際には認証コードが必要になります。メール本文に認証コード変換文字列${VERIFY}を指定してください。

<feed>
<entry>
<contributor>
<uri>urn:vte.cx:auth:{メールアドレス}</uri>
</contributor>
<title>メールのタイトル(任意)</title>
<summary>メールの本文(任意)</summary>
</entry>
</feed>

PUT /d?_changeaccount_verify={認証コード}で実際にアカウント変更を実行します。

注) サービス作成者のアカウント変更を行う場合、作成したサービスとシステム管理サービスそれぞれについてアカウント変更を実施してください。 アカウント名が一致していないと、システム管理サービスから作成したサービスへのログインができません。

アカウント削除

DELETE /d?_deleteuser={アカウント|uid}で指定されたアカウントの削除を行います。アカウントかuidのいずれかを指定できます。

DELETE /d?_deleteuserで本文(body)にアカウントエントリを指定することで複数のユーザを削除できます。

<feed>
    <entry>
    <link rel="self" href="/_user/{uid}" />
    <title>{アカウント|uid}</title>
    </entry>
    ・・・
    </feed>

システムグループ

システムグループは複数のユーザーの権限をまとめて管理するために、システムがあらかじめ定義しているグループです。
つまり、 /_groupフォルダ配下にグループエントリ、その配下にuidエントリを作成し、/_user/{uid}/groupへのaliasを付与することで、ユーザ(uid)がシステムグループに参加したものとして認識されます。uidはサービスを作成した本人のものが使われます。

例：サービス管理者権限のグループエントリ

<feed>
  <entry>
    <id>/_group/$admin/216,3</id>
    <link href="/_group/$admin/216" rel="self" />
    <link href="/_user/216/group/$admin" rel="alternate" />
    <published>2018-06-07T14:32:40.444+09:00</published>
    <updated>2018-06-09T11:08:47.328+09:00</updated>
  </entry>
</feed>

/_group/$adminグループに属することでサービス管理権限が付与されます。
システムグループには以下のものがあります。
(システムグループは $adminのように$で始まる名前のグループです）

• サービス管理権限：/_group/$admin
  • サービスの作成、削除、アプリケーションログの参照やACLやindexなどの設定が可能
  • <contributor>タグおよび、<rights>タグの内容を自由に編集可能
  • /_settingsフォルダにはサービス管理権限のACL(CRUD)が付与されている
• ユーザ管理権限：/_group/$useradmin
  • ユーザの作成、削除、ユーザステータスの変更、パスワード変更が可能
• コンテンツ管理権限：/_group/$content
  • HTMLやJavaScript等のページやコンテンツの登録、削除が可能
  • <content>タグのテキストノードの内容を自由に更新可能

ユーザ作成グループ

ユーザ作成グループはユーザが自由に定義できるグループで/_user/{uid}配下にあるものです。
/_user/{uid}/group/{グループ名} というエントリを作成することで、ユーザ作成グループを作ることができます。
※ユーザ作成グループは署名が必要です。詳しくは署名を参照してください。

グループ署名のパターンには、以下の２つがあります。グループ署名は作成者、参加者双方の署名を必須とします。

• ①親がグループを作成→子がそのグループに参加申請→親が署名して参加承認
• ②親がグループを作成→親が子に参加依頼→子が署名して参加

例)
    * グループ名: /_user/123/mygroup -> created uid=123

    * グループ作成者uid: 123
    * グループ参加者uid: 456

    ①の場合
    * 子がそのグループに参加申請
    * 以下のエントリーを登録
        * idキー: /_user/123/mygroup/456
        * alias: /_user/456/group/mygroup
    * 以下のキーに署名
        * alias: /_user/456/group/mygroup uid=456
    * 親が署名して参加承認
        * idキー/_user/123/mygroup/456のtitleに署名。uid=123
    * 参加者のグループ参加チェック
        * /_user/456/group配下をfeed検索
        * /_user/456/group/mygroupのidキーが/_user/123/mygroup/456なので、署名検証を行う。(/_groupで始まらない、かつ自uidとグループ名のUIDが異なるため)
            * /_user/123/mygroup/456の署名検証を行う。uid=123
            * /_user/456/group/mygroupの署名検証を行う。uid=456

    ②の場合
    * 親が子に参加依頼
    * 以下のエントリーを登録
        * idキー: /_user/123/mygroup/456
        * alias: /_user/456/group/mygroup
    * 以下のキーに署名
        * idキー: /_user/123/mygroup/456 uid=123
    * 子が署名して参加
        * alias/_user/456/group/mygroupのtitleに署名。uid=456
    * 参加者のグループ参加チェック
        * /_user/456/group配下をfeed検索
        * /_user/456/group/mygroupのidキーが/_user/123/mygroup/456なので、署名検証を行う。(/_groupで始まらない、かつ自uidとグループ名のUIDが異なるため)
            * /_user/123/mygroup/456の署名検証を行う。uid=123
            * /_user/456/group/mygroupの署名検証を行う。uid=456

フォルダACL

vte.cxでは、これまで述べたように、エンドポイントURLをフォルダに見立てて、その配下にリソースを格納できます。また、そのフォルダにACLを設定することで自身および配下のエントリについてアクセスコントロールを設定できます。
ACLは以下のようにエントリのcontributorタグに指定します。特定のユーザ(uid)、ログイン済ユーザ(+)、すべてのユーザ( *)、あるいはグループ(GroupKey)を設定できます。グループ指定ではワイルドカードの指定も可能です。(/group*など)

<contributor>
    <uri>urn:vte.cx:acl:{uid|*|+|GroupKey},{C|R|U|D|E|.|/}</uri>
</contributor>

ACLの種類 (複数指定可能だが「E」「.」「/」のみの指定は不可)

• C : 登録処理を許可
• R : 検索処理を許可
• U : 更新処理を許可
• D : 削除処理を許可
• E : サーバサイドJavaScriptからのみデータ操作可でHTTP(S)からのデータ操作が不可となる。
• . : Own このエントリのみ適用される。配下のエントリには適用されない。
• / : Low このエントリより配下のものについて適用される。指定したエントリ自体には適用されない。
• Own.Low/いずれも設定されていない場合は両方(./)が付いているとみなされる

権限のスコープ

• 数字 : ログインしているユーザ(uid)が対象
  • 先頭と末尾にワイルドカード(*)を指定可能
• * : ログインしていないユーザを含むすべてのユーザが対象
• + : ログインしているすべてのユーザが対象
• スラッシュ(/)で始まるもの : グループ(GroupKey)が対象

ACLの適用範囲

• 自身の階層を含む上位階層のACLが適用される。
  • つまり、自身にはACL設定がなくても親フォルダ（さらに上も）に設定されていれば親のACLが有効になる。
• 親フォルダにACLが設定されて、かつ、自身にもACLが設定されている場合、自身の設定が優先される。
  • 同様に、配下のエントリにACLの設定がある場合、上位階層で設定されたACLではなく配下のエントリのACLが有効となる。
• 検索結果のうち参照権限がないエントリについては検索結果に含められない。
• aliasのキーについてもACLが適用される。

ACLの追加と削除

以下をリクエストすることでACLを追加できます。

PUT /d/?_addacl

<feed>
  <entry>
    <link rel="self" href="{キー}" />
    <contributor>
      <uri>urn:vte.cx:acl:{ACL対象},{権限}</uri>
    </contributor>
  </entry>
</feed>

また、PUT /d/?_removeaclで指定したACLを削除できます。 

項目ACL

/_settings/templateエントリのタグに記述することで項目に対してACLを設定することができます。ACLにはユーザおよびグループの読込(R)または書込(W)権限を指定できます。
以下のように、項目名に続けて=の後に、{uid|group}+{RW}の形式でACLを指定します。 ,(カンマ)で複数件指定できます。

subInfo.favorite.food=3+W,/grp1+W,/*+R 　 

/_settings/templateエントリのrightsタグにはIndexも指定できますが、以下のようにindexとACLを同時に記述することができます。:コロンの右辺がIndex、=の右辺がACLになります。

subInfo.favorite3.food:/[0-9]+/(self|alias)=1+W　　 

暗号化項目

項目名に続けて#を付けると暗号化項目となります。Index項目と暗号化項目はどちらか一つを指定できます。 暗号化では、vte.cx内部で持っている秘密Key(usersecret)とidと組み合せてハッシュ化したものが実際の暗号化において使われます。 
　以下はcontributor.uriを暗号化する設定例です。

contributor.uri#　　　　　　　　　　　　　 

　また、以下のように、暗号化と項目ACLは同時に設定できます。これは、rightsの暗号指定、かつ、自身と/_group/$adminグループのRW権限の付与を意味します。

rights#=@+RW,/_group/$admin+RW　　 

システムフォルダと各種設定

システムフォルダ

_から始まるフォルダをシステムフォルダといいます。システムフォルダはシステムが管理する特殊なフォルダであり以下の種類があります。

• /_group：システムグループフォルダ
  • システムグループを管理します。詳細は「システムグループ」を参照してください。
• /_user：ユーザフォルダ
  • 配下にユーザを管理します。詳細は「ユーザエントリ」を参照してください。
• /_html：htmlコンテンツフォルダ
  • 配下のエントリーはHTML、CSSやJavaScript、画像などのコンテンツを格納できます。Webサーバのrewrite機能により、/_html は / にマッピングされます。
• /_settings：各種設定情報
  • 各種設定情報を管理します。詳細は「各種設定情報」を参照してください。
• /_log：ログ
  • 配下にシステムやアプリケーションによって出力されたログが降順(最新が先頭）で記録されます。
  • ログには、updated : 更新日時、title : タイトル、subtitle : サブタイトル、summary : 内容が書かれます。
• /_security：認証の失敗回数を格納
  • 詳しくは「DoS攻撃対策のIP Blacklist」を参照してください。

各種設定情報

vte.cxの設定情報は以下のように/_settings配下で管理されます。これらは、直接編集もできますが、管理画面の「メール・詳細設定」でも設定できます。（推奨）

• /_settings/properties：プロパティ情報
• /_settings/template：エントリスキーマやIndex、項目ACLなど
• /_settings/bigquery.json：BigQuery用サービスアカウント秘密鍵ファイル
• /_settings/adduser：ユーザ登録時(?_adduser)に送られるメール本文
• /_settings/passreset：パスワードリセット時(?_passreset)に送られるメール本文

プロパティ情報

プロパティ情報(/_settings/properties)のrightsタグにおいて以下のような情報を設定できます。ここで設定されていないものについてはシステム内部で持つ設定情報がデフォルトで使用されます。RXIDの詳細については「認証キーとトークン」を参照してください。

_entry.number.default : エントリーGET時のデフォルト最大数 [100]
_rxid.minute : RXID(WSSE)有効時間(分) [120]
_rxid.counter.{連番}.{回数} : 同じRXIDを使用しても指定回数まで許可されるURLパターンを指定。
_session.minute : セッション有効時間 [30]

エラーページ設定

以下はエラーページの設定です。これは、アクセス時にエラーが発生した場合にリダイレクトするルールを設定します。
また、リダイレクトする際に、Cookieの「ERROR_STATUS」にHTTPステータスコードが、また「ERROR_MESSAGE」にエラーメッセージがセットされます。このCookieは10秒間だけ有効です。

_errorpage.{適用順}.{エラーページselfid}={PathInfoの正規表現} : エラー画面表示URLパターン(正規表現) 

confirm.html表示中にエラーの場合はerror.htmlに遷移する。それ以外のエラーはlogin.htmlに遷移する設定例

_errorpage.1.error.html=^/_html/confirm.html$
_errorpage.2.login.html=^/_html/.*$

メール送信設定

以下はメール送信の設定です。これが設定されていないとユーザ登録においてメール送信ができないため本人確認ができません。ご自身でEmailを用意して設定してください。

_mail.from.personal : EMailの送信元名
_mail.from : Emailのfrom
_mail.transport.protocol : smtpsなどのメール送信プロトコル
_mail.password : メール送信アカウントのパスワード
_mail.smtp.host : メール送信ホスト
_mail.smtp.port : メール送信ポート
_mail.smtp.auth : true/false

BigQuery接続設定

以下はBigQueryに接続するための設定です。
これとは別に、/_settings/bigquery.jsonに、サービスアカウントの秘密鍵JSONを登録する必要があります。BigQueryを使用するためにはGoogle Cloud Platformプロジェクトを作成し、BigQueryを有効にする必要があります。

 _bigquery.projectid : プロジェクトID
 _bigquery.dataset : データセット名
 _bigquery.location : ロケーション(デフォルト値は asia-northeast1)

プロジェクトの作成とIDの確認

まず、Googleアカウントを取得します。
(https://accounts.google.com) のログイン画面からアカウントを作成を選択しアカウントを作成します。
1.作成したアカウントで Google Cloud Platform にログインします。(https://console.cloud.google.com)
2.プロジェクトを作成します。
　左上のGoogle Cloud Platformという題名の隣にプロジェクトの選択 ▼というリスト項目が表示されているのでクリックします。
　既に別のプロジェクトを作成し選択している場合、プロジェクト名が表示されます。
　表示された画面右上の新しいプロジェクトを選択し、新規プロジェクトを作成します。
3.プロジェクトIDの確認
　Google Cloud Platform のホーム画面に表示されるプロジェクト情報にプロジェクトIDが表示されます。

Billingの設定

BigQueryを使用するにはBillingの設定が必要です。
Google Cloud Platform の左メニューから「お支払い」を選択し、請求先アカウントを追加します。

データセットの作成

Google Cloud Platform の左メニューからBigQueryを選択すると、BigQueryの管理画面が表示されます。(https://bigquery.cloud.google.com)
BigQuery管理画面の左メニューより、プロジェクト名の横の下三角▼をクリックします。
Create new datasetを選択し、データセットを作成します。
データセットID、ロケーションを入力します。

BigQueryのサービスアカウント秘密鍵の作成

サービスアカウントとは、Googleの各サービスに対する権限を持つアカウントです。Googleのサービスに対しAPIリクエストを行う際に認証情報として使用します。
Google Cloud Platform の左メニューからIAMと管理-サービスアカウントを選択します。
画面上部のサービスアカウント表題の隣にある＋サービスアカウントを作成をクリックします。
　　1.サービスアカウント名: 任意の値を入力
　　2.Project role: BigQuery-BigQueryユーザーおよびBigQueryデータオーナーを選択
　　3.新しい秘密鍵の提供にチェックを入れます。キーのタイプをJSONとします。
　　4.保存をクリックします。
サービスアカウントが作成されます。同時に、JSON形式の秘密鍵がダウンロードされます。

認証キーとトークン

アクセストークン

アクセストークンは時間制限なしの認証トークンであり、スマホアプリからの認証の他、サービスデプロイ時の認証トークンとしても使われます。

ログイン後、GET /d/?_accesstoken で取得できます。 feed.titleにアクセストークンが入ったものが返ります。

<feed>
  <title>{Accesstoken}</title>
</feed>

リクエスト時にAccesstokenをリクエストヘッダに付与することで認証されます。
認証が成功してもログイン状態にはなりません。

Authorization : Token {Accesstoken} 

リンクトークン

リンクトークンはアクセストークンと同様に時間制限なしの認証トークンですが、アクセスできるURLに制限が付けられています。
　これは、メールに含まれるURLリンクとして使うことを想定しています。送信するメールの本文に以下のように${LINK=...}を挿入することで、Linktokenを含むURLが自動的に組み立てられます。

挿入文

${LINK=/setpass.html}&value=abc 

実際のメール本文

https://test.vte.cx/setpass.html?_token=xxx&value=abc 

URLリンク(上記Linktoken)をクリックするとsetpass.htmlが表示されます。
ただし、ログイン状態にはなりません。
Keyを /foo と指定した場合、 許可される操作は以下のみです。

• /fooのエントリ検索、フィード検索が可能
• /foo 配下のエントリをPOST可能(自動採番）
• /foo エントリーをPOST、PUT、DELETE可能

また、リンクトークンは、ログイン後、GET ?_linktoken={Key1[,Key2],・・} をリクエストすることでも取得できます。 KeyにはURLのPathinfoを指定します。カンマで区切ることで複数指定できます。Keyに含まれる#はuidに変換されます。

アクセスキー

アクセスキーは、アクセストークンやリンクトークンを発行するために使用されるシークレットキーであり、サーバ内(/_user/{uid}/accesskeyエントリ)に保持しています。
　アクセスキーを更新することで、これまで発行したアクセストークンやリンクトークンを無効にすることができます。つまり、アクセストークンが悪意のある第三者に漏洩してしまった場合、そのアクセストークンに認可されているあらゆる操作が永久に実行可能になるため、アクセスキーを更新してこれを防ぐ必要があります。

PUT /d/?_accesskeyでアクセスキーを更新します。更新するとこれまで使っていたアクセストークンやリンクトークンは使えなくなります。

ワンタイムトークン(RXID)

ワンタイムトークン(RXID)は鍵付きハッシュを利用した認証トークンです。ワンタイムであり一度認証が実行されると同じものはもう使えません。これは、AndroidやiPhoneなどのスマホのログイン認証で使うことを想定しています。また、異なるサービス間で通信が必要になった場合にも使われることがあります。
トークン生成にはユーザアカウント、パスワード、APIキー(後述)、サービス名を使用します。ハッシュ化された文字列なのでネットワーク上で生のパスワードが流れる心配はありません。

ログイン後、GET /d/?_getrxidを実行することでRXIDを取得できます。
RXIDは、 GET /d/?_RXID={RXID文字列}で認証されます。認証後はログイン状態になります。また、以下のようにリクエストヘッダにつけて認証することもできます。

Authorization: RXID {RXIDトークン} 

RXIDの有効時間や実行可能回数は、設定ファイル(/_settings/propertiesのrightsタグ)に指定します。

• _rxid.minute : 有効時間(分)。[デフォルト15分]
• _rxid.counter.連番.回数 : 同じRXIDを使用しても指定回数まで許可されるURLパターンを指定

_rxid.minute=60
_rxid.counter.1.10000=^/_html/foo.html.*$

APIキー

APIキーはワンタイムトークン(RXID)などに使用されるクライアントシークレットキーです。また、サーバサイドJavaScriptにおいてサービスを跨ぐAPI実行の際にもAPIキーが必要になります。サービスに対してAPIキーを１つ発行します。

APIキーを更新したい場合は以下を実行します。サービス管理者が実行できます。

PUT /d/?_apikey

APIキーを更新すると、これを保持している全てのクライアントから認証ができなくなります。第三者に漏洩してしまった場合などはAPIキーを更新することで悪意のある操作を防ぐことができます。ただし、更新した場合は新しいAPIキーをクライアントや他のサービスに配布する必要があります
　APIキーを更新してもアクセストークンやリンクトークンには影響はありません。これらを無効にしたい場合はアクセスキーを更新してください。

スマホアプリからのログイン方法

スマホアプリからログインするにはRXIDを使います。
RXIDを生成するライブラリであるvtecxauthパッケージをnpmで公開しています。まず、nodeをインストールし、npm install vtecxauthでvtecxauthパッケージをインストールしてください。 vtecxauthパッケージの vtecxauth.getRXID()メソッドを実行することでRXIDを取得することができます。
パラメータには、ユーザアカウント、パスワード、サービス名、APIキーを指定します。APIキーは管理画面で確認できます。

vtecxauth.getRXID(username: string, password: string, servicename: string, apikey: string): string;

以下はRXIDを使った認証の例です。初回はRXIDで認証してcookieを保存し、2回目以降はcookieを使って認証してください。（サーバではセッションが生成されています）
セッションが不要な場合はcookieの代わりにアクセストークンを使用してください。アクセストークンを使う場合はセッションは生成されずタイムアウトもありません。

// 初回(RXIDでログイン)
const rxid = vtecxauth.getRXID(username, password, servicename, apikey)

axios({
    url: 'http://{サービス名}.vte.cx/d',
    method: 'get',
    headers: {
        'Authorization: RXID '+ rxid,
        'X-Requested-With': 'XMLHttpRequest'
    }
}).then((result) => {
    cookie = result.headers['set-cookie'][0].split(';')[0]  // cookieを保存
}).catch((error) => {
    ・・・
})

// ２回目以降(cookie認証)
axios({
    url: 'http://{サービス名}.vte.cx/d',
    method: 'post',
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'Cookie': cookie
    },
    data : reqdata          
}).then((result) => {
    ・・・
}).catch((error) => {
    ・・・
})

署名

Entryに署名をつけることでユーザが承認したことを示す記録を残すことができます。グループにおけるメンバー承認のプロセスにおいても署名が使われます。

キーはselfまたはエイリアスに署名を付けることができます。ただし、キーのuidはログインユーザと一致する必要があります。つまり、/_user/{uid}で始まるキーに対してのみ署名可能です。そうでない場合、署名不可エラーとなります。

    <link rel="{self | alternate}" href="{キー}" title="{revision},{uid},{署名}" />

以下で署名を付与できます。

PUT {キー}?_signature&r={リビジョン(任意)}

正常に署名できた場合、HTTPステータスコード200(A signature has been applied.)が返ります。ログインしていない場合、401が、指定されたKeyに署名する権限がない場合、403が返ります。

既に署名が付いている場合は更新します。更新の際はRevisionを+1し、更新時刻を新たに設定します。署名ができるのは、idのキー、またはエイリアスのキーのみです。

以下で署名を削除できます。

DELETE {キー}?_signature&r={リビジョン(任意)}

削除が成功すると、linkタグのtitle属性に"-"(署名削除)を設定します。(署名がないものとの区別が必要になるケースがあるため、ブランクにするのでなく、無効な値(-)をセットする必要があります。)

正常に署名を削除できた場合、HTTPステータスコード200が返ります。ログインしていない場合、401が、指定されたKeyに署名する権限がない場合、403が返ります。

署名削除の際も通常の更新と同じくRevisionを+1し、更新時刻を新たに設定します。

以下で署名を検証できます。

GET {キー}?_signature

指定するキーは、署名検証したいキーです。キーでなくエントリーそのものの参照権限がある場合、署名検証を可能とします。

正常に署名を検証できた場合、HTTPステータスコード200が返ります。署名が不正である場合、412(The signature is invalid.)が返ります。キーのエントリーそのものを参照する権限がない場合、403が返ります。

DoS攻撃対策

IP Blacklist

ブラックリストに登録することでDoS攻撃などの可能性があるリクエストを拒否（ブロック）できます。ブラックリストに登録されているユーザ・IPアドレスの組み合わせからのリクエストは認証エラーとなります。特定のIPから1000回(デフォルト)以上ログイン失敗でユーザ・IPアドレスの組み合わがブラックリストに自動的に追加されます。ブラックリストに追加されても異なるIPからログインすることは可能です。

ブラックリストは認証失敗カウンタによって管理します。認証失敗カウンタは、/_security/{アカウント認識文字列}/{IPアドレス}キーのカウンタが使われます。

• アカウント認識文字列は、WSSEやRXIDの場合はアカウント (ユーザ名から使用不可文字を除去した文字列)が、AccessTokenやLinkTokenの場合はuidが使われる

ブラックリストのブロックは最後に認証失敗してから24時間後(デフォルト)に解除されます。または、認証失敗カウンタを0にすることでブロックを解除できます。具体的には以下のようなリクエストです。

ブロック解除

DELETE /d/_security/{アカウント認識文字列}/{IPアドレス}?_cachelong 

サーバサイドJavaScript

vte.cxのアプリケーションを作成すると基本的にSPA(Single Page Application)になります。SPAのスタイルでは、サーバサイドでレンダリングするのではなく、クライアントからはAjax(XHR)を用いてサーバのAPIにアクセスし、サーバはJSONデータを返すのみとなります。サーバサイドは純粋なAPIとなり、複雑さがサーバサイドからクライアントに移動していることから、これはThin server architecture とも呼ばれます。
　しかし、ビジネスロジックをもたない純粋なREST APIだけで構築すると開発生産性やパフォーマンスを大きく損ねることがあります。あまりにもクライアント側にビジネスロジックが偏重しすぎて開発工数が膨らんでしまうのです。また、クライアントから何回もAPIを呼ぶいわゆるN+1問題も発生しがちです。
　実はクライアントよりもサーバ側でビジネスロジックを実行する方が有利であることがわかっています。つまり、クライアントはビジネスロジックを持たない単純なViewとし、Viewに必要なデータの組み立てなどはサーバ側で行うことで、クライアント側へのビジネスロジック偏重を防ぎます。こうすることで、N+1問題も解決できます。
　このスタイルを、BFF(Backend for Frontend)といいます。vte.cxではサーバサイドのBFFにもJavaScriptを採用することで、統一的(Isomorphic)な環境で高い生産性を発揮できるようにしています。
　BFFは実はフロントエンドアプリケーションの範疇になります。重要なポイントは、あくまでフロントエンドのアプリケーションとしてサーバサイドJavaScriptを実装するということであり、データベース設定や認証設定などのようなサーバ構築のための設定などではないという点です。

サーバサイドJavaScriptの設定方法と実行の仕組み

サーバサイドJavaScriptを設定する方法は簡単で、/serverフォルダ配下にJavaScriptファイルを格納するだけです。また、GET|POST|PUT /s/{スクリプト名}のようにリクエストすると、/serverフォルダに格納されている {スクリプト名}.jsファイルがサーバ上で実行されます。
　サーバサイドJavaScriptの実行時間は同期リクエストで最大５分までで、それを超えると強制的にキャンセルされます。長時間かかる場合は_asyncパラメータを付けて非同期リクエストを実行してください。非同期リクエストでは別スレッドが起動し、ステータス202 Acceptedをレスポンスします。実際の処理はバッチジョブサーバで実行されるため、バッチジョブサーバに設定されたタイムアウト時間が最大の実行時間になります。

サーバサイドJavaScriptのビルドとデプロイ

サーバサイドJavaScriptは、TypeScriptで書かれたソースコードをWebpackなどによりECMAScript5の形式に変換されたものを実行します。 これは、以下のようにビルドします。

ログイン

　管理画面にてサービスを作成後(仮にfooserviceとします）、githubのブランクプロジェクトをチェックアウトして、npm installします。その後、以下のコマンドでログインします。アカウントとパスワードはサービス作成で使ったものと同じもの使用してください。

npm run login

service:fooservice
is production?:n
login:foo@bar.com
password:*********
Logged in.

ビルドとデプロイ

　以下のコマンドを実行するとssr.html.tsxをビルド＆デプロイできます。また、ソースを更新すると自動的にビルド＆デプロイされます。デプロイ後、/s/ssr.htmlをブラウザで開いて確認してください。

npm run watch — --env entry=/server/ssr.html.tsx

クライアントコードの開発

　以下のコマンドを実行するとクライアントコードの開発環境が開きます。(webpack-dev-serverが起動します)

npm run serve:index

npm run serve:login

npm run serve — --env entry=/components/hello.tsx

Reactとvtecxapiを利用してSSRを実行する

vtecxapiパッケージをインポートすることでサーバサイドJavaScriptからvte.cxのAPIを利用することができます。まず初めにnpm install vtecxapiでvtecxapiパッケージをインストールしてください。
　以下はReactの機能を使ってSSR(サーバサイドレンダリング)を実行するサンプルです。最後の行のHTMLを返却するところでvtecxapiが使われています。
　以下をデプロイして、/s/ssr.htmlにアクセスすると、「Hello, World!」が表示されるのを確認できます。 

// server/ssr.html.tsx
import * as vtecxapi from 'vtecxapi'
import * as React from 'react'
import * as ReactDOMServer from 'react-dom/server'

const element = (
    <h3> Hello, World! </h3>
)

const html = ReactDOMServer.renderToStaticMarkup(element)

vtecxapi.doResponseHtml(html)

vtecxapiを利用してJSONを返すサービス

vtecxapi.doResponse()により、オブジェクトをJSONなどに変換してクライアントに返すことができます。サーバサイドのビジネスロジックはこのような形でJSONを返すサービスとして実装することが多いと思われます。
以下は/fooエントリを取得してJSONを返すサンプルです。
　前述のサンプルでは、コンテンツを返すのに、doResponseHtml()を使っていましたが、JSONなどのデータを返すには、doResponse()を使います。 ちなみに、doResponse()は、リクエストパラメータにデータタイプを指定することで様々なデータ形式に変換することができます。例えば、/registration?xでxml、/registration?mでMessagePackを返すことができます。

// server/registration.tsx
import * as vtecxapi from 'vtecxapi'

const feed = vtecxapi.getFeed('/registration')   // /registration?xでxmlになる
vtecxapi.doResponse(feed) 

また、vtecxapi.getFeed()は検索条件を指定して検索することができます。
検索条件の文字列に&が含まれる可能性がある場合は、encodeURIComponent()などを使って必ずエンコードしてください。レスポンスの最初のエントリのrightsに文字列(nextpagelink)が格納されている場合、次ページが存在することを示します。次のリクエストにて、p={nextpagelink}パラメータを付けることで次ページを取得できます。

// server/registration.tsx
import * as vtecxapi from 'vtecxapi'

const param = encodeURIComponent(vtecxapi.getQueryString('param'))
const feed = vtecxapi.getFeed('/registration?param='+param)   // /registration?xでxmlになる
vtecxapi.doResponse(feed) 

ファイルアップロード

リソースの登録更新では、raw形式のバイナリの他にFormDataオブジェクトを使ったアップロードを行えます。FormDataオブジェクトはmultipart/form-data形式のデータであり、ブラウザから直接アップロードすることができます。
アップロードファイルが一つでありキーも指定されていない場合、アップロードしたファイル名がエントリのKeyとして登録されます。アップロードファイルが複数の場合は以下のようにサーバサイドJavaScriptを使って処理することができます。
vtecxblankに複数のファイルを登録するサンプルプログラム(upload_pictures_sample)があります。これは、クライアントから２つの画像データを送信してサーバに登録するサンプルです。
サーバサイドJavaScriptのvtecxapi.saveFiles(param)は、ファイルアップロードにおけるMultipart Postリクエストをサーバ側で処理するために使用します。具体的には、saveFiles(param)で指定するparamオブジェクトに、inputタグのnameをキーにして任意のファイル名を設定します。
サービスを作成し、デプロイしてログインすると、/upload_pictures_sample.htmlを表示できますので、そこから２つの画像ファイルをアップロードしてみてください。アップロードに成功すると、http://{サービス名}.vte.cx/{アップロードファイル名}でブラウザに表示して確認できます。（※ サービスの作成方法については、チュートリアルを参照してください。）

画面側(upload_pictures_sample.tsx)

import * as React from 'react'
import * as ReactDOM from 'react-dom'
import axios, { AxiosError } from 'axios'
import {
    Form,
    FormGroup,
    FormControl,
    Button
} from 'react-bootstrap'

/* コンポーネントのPropsの型宣言 */
interface ComponentProps {
}
/* コンポーネントのStateの型宣言 */
interface ComponentState {
    picture1: any,
    picture2: any,
    [propName: string]: any
}

class UploadPictureForm extends React.Component<ComponentProps, ComponentState> {
    constructor(props: ComponentProps) {
        super(props)
        this.state = { picture1: {}, picture2: {} }
    }

    handleChange(e: React.FormEvent<any>) {

        if (e.currentTarget.files) {
            const file = e.currentTarget.files.item(0)
            if (file) {
                const key = '/_html/img/' + encodeURIComponent(file.name)
                const name = e.currentTarget.name

                // 画像以外は処理を停止
                if (!file.type.match('image.*')) {
                    return
                } else {
                    // 画像表示
                    let reader = new FileReader()
                    reader.onload = () => {
                        this.setState({ [name]: { value: reader.result, key: key } })
                    }
                    reader.readAsDataURL(file)
                }
            }
        }

    }

    handleSubmit(e: React.FormEvent<any>) {
        e.preventDefault()

        const formData = new FormData(e.currentTarget)
        const param = (this.state.picture1.key ? 'key1=' + this.state.picture1.key + '&' : '') +
            (this.state.picture2.key ? 'key2=' + this.state.picture2.key : '')

        // 画像は、/d/_html/img/{key} としてサーバに保存されます
        axios({
            url: '/s/savefiles?' + param,
            method: 'post',
            headers: {
                'X-Requested-With': 'XMLHttpRequest'
            },
            data: formData

        }).then(() => {
            alert('success')
        }).catch((error: AxiosError) => {
            if (error.response) {
                alert('error=' + JSON.stringify(error.response))
            } else {
                alert('error')
            }
        })

    }

    render() {
        return (
            <Form horizontal onSubmit={(e) => this.handleSubmit(e)}>
                <img src={this.state.picture1.value} />
                <br />
                <img src={this.state.picture2.value} />
                <br />
                <FormGroup>
                    <FormControl type="file" name="picture1" onChange={(e) => this.handleChange(e)} />
                </FormGroup>
                <FormGroup>
                    <FormControl type="file" name="picture2" onChange={(e) => this.handleChange(e)} />
                </FormGroup>
                <FormGroup>
                    <Button type="submit" className="btn btn-primary">
                        登録
                    </Button>
                </FormGroup>
            </Form>
        )
    }
}

ReactDOM.render(<UploadPictureForm />, document.getElementById('container'))

サーバサイドJavaScript(/server/savefiles.tsx)

import * as vtecxapi from 'vtecxapi'

interface Param {
    picture1: string
    picture2: string
}

const param: Param = {
    picture1: vtecxapi.getQueryString('key1'),
    picture2: vtecxapi.getQueryString('key2')
}

vtecxapi.saveFiles(param)

CSVデータアップロード

サーバサイドJavaScriptを利用することでCSVデータのアップロードを行うことができます。vtecxapi.getCsv(header[],items[],parent,skip,encoding)は、指定したパラメータを元にCSVを受信してJSONオブジェクトに変換します。パラメータの意味は以下の通りです。

• headerにはCSVのヘッダ情報を指定する。 受信したCSVファイルのヘッダ情報と異なれば {"feed":{"entry":[{"title" : "Header parse error"}]}}のようにパースエラーとなる。
• itemsには対応するJSONの項目名を指定する
  • item1(int)やitem1(boolean)のようにカッコの中にintやbooleanの型を指定可能
• parentには変換後のJSONの親項目を指定する。
• skipにはCSVファイルの読み飛ばす行数を指定する。
• encodingはCSVファイルの文字コードを指定する。(UTF-8,Windows-31J等)

vtecxblankプロジェクトには以下のサンプルプログラムがあります。
デプロイしてログインすると、/upload_csv_sample.htmlを表示できますので、その画面から/data/sample.csvを指定してアップロードしてください。アップロードに成功するとログに読み取った結果のJSONを表示しますので、管理画面のログで確認してください。

画面側(upload_csv_sample.tsx)

import * as React from 'react'
import * as ReactDOM from 'react-dom'
import axios, { AxiosError } from 'axios'
import {
    Form,
    FormGroup,
    FormControl,
    Button
} from 'react-bootstrap'

/* コンポーネントのPropsの型宣言 */
interface ComponentProps {
}
/* コンポーネントのStateの型宣言 */
interface ComponentState {
}

class UploadCsvForm extends React.Component<ComponentProps, ComponentState> {
    constructor(props: ComponentProps) {
        super(props)
        this.state = {}
    }

    handleSubmit(e: React.FormEvent<any>) {
        e.preventDefault()

        const formData = new FormData(e.currentTarget)

        // 画像は、/d/registration/{key} としてサーバに保存されます
        axios({
            url: '/s/getcsv',
            method: 'post',
            headers: {
                'X-Requested-With': 'XMLHttpRequest'
            },
            data: formData

        }).then(() => {
            alert('success')
        }).catch((error: AxiosError) => {
            if (error.response) {
                alert('error=' + JSON.stringify(error.response))
            } else {
                alert('error')
            }
        })

    }

    render() {
        return (
            <Form horizontal onSubmit={(e) => this.handleSubmit(e)}>
                <FormGroup>
                    <FormControl type="file" name="csv" />
                </FormGroup>
                <FormGroup>
                    <Button type="submit" className="btn btn-primary">
                        登録
                    </Button>
                </FormGroup>
            </Form>
        )
    }
}

ReactDOM.render(<UploadCsvForm />, document.getElementById('container'))

サーバサイドJavaScript(/server/getcsv.tsx)

import * as vtecxapi from 'vtecxapi'

const items = ['item1', 'item2(int)', 'item3(int)']
const header = ['年月日', '件数', '合計']
const parent = 'order'
const skip = 1 // 1行スキップ
//const encoding = 'Windows-31J'
const encoding = 'UTF-8'

// CSV取得
const result = vtecxapi.getCsv(header, items, parent, skip, encoding)
vtecxapi.log(JSON.stringify(result)) 

CSVデータ(/data/sample.csv)

// 1行skip
年月日,件数,合計
"2017/7/5",3,3
"2017/7/6",5,8
"2017/7/7",2,10

PDF出力

ReactのSSR(Server Side Rendering)機能とvtecxのPDF出力機能を組み合わせることで動的にPDFを生成することができます。vtecxapi.toPdf(pages,html,outfilename)は、指定したパラメータを元にPDFを生成します。パラメータの意味は以下の通りです。

• pagesには出力するPDFのページ数を指定
• htmlにはPDFの生成元となるHTMLを指定(テンプレートHTML)
• outfilenameにはPDFのファイル名を指定

vtecxblankプロジェクトには以下のサンプルプログラムがあります。
デプロイ後にログインして /s/ssr.pdfにアクセスすると、「Hello, Harper Perez」と表示されたpdfがダウンロードされます。
/pdf/pdfstyles.tsはPDFのレイアウト等を指定するスタイルシートファイルです。以下のようにstyles属性に指定することで色やサイズなど様々なスタイルを設定することができます。詳しくは、「PDFスタイルシート」を参照してください。

サーバサイドJavaScript(/server/ssr.pdf.tsx)

import * as vtecxapi from 'vtecxapi'
import * as React from 'react'
import * as ReactDOMServer from 'react-dom/server'
import * as pdfstyles from '../pdf/pdfstyles'

interface User {
    firstName: string
    lastName: string
}

function formatName(user: User) {
    return user.firstName + ' ' + user.lastName
}

const user: User = {
    firstName: 'Harper',
    lastName: 'Perez'
}

const element = (
    <html>
        <body>
            <div className="_page" style={pdfstyles._page}>
                <table style={pdfstyles._table}>
                    <tr>
                        <td>
                            <p> Hello, {formatName(user)}! </p>
                        </td>
                    </tr>
                </table>
            </div>
        </body>
    </html>
)

const html = ReactDOMServer.renderToStaticMarkup(element)

// PDF出力
vtecxapi.toPdf(1, html, 'test.pdf')

PDF用スタイルファイル(/pdf/pdfstyles.ts)

export const _page: any = {
    pagesize: 'A4',
    orientation: 'portrait'
}

export const _table: any = {
    bgcolor: '#FFEC8B',
    frame: 'box',
    cellspacing: '3',
    cellpadding: '3',
    width: '90%',
    align: 'left'
}

メール送信

vtecxapi.sendMail(entry: any, to: string[] | null, cc?: string[], bcc?: string[], attachments?: string[])によりメールを送信することができます。
パラメータには以下を指定します。

• entry
  • title : メールのタイトル
  • summary : テキストメール本文(必須)
  • content : HTMLメール本文(任意、インライン画像を指定可能)
• to : 送信先アドレス (複数指定の場合配列で指定)
• cc : CCでの送信先アドレス (配列で指定)
• bcc : BCCでの送信先アドレス (配列で指定)
• attachments : 添付ファイル(コンテンツのキーを複数指定可能)

entryのsummaryにはテキストメール本文を、contentにはHTMLメール本文を指定します。HTMLメールを送信できない場合はテキストメールが送信されます。
HTMLメールのインライン画像は <img src="CID:/_html/img/ajax-loader.gif">のように、CIDに続けてキーのURLを指定します。
以下はメールを送信するvtecxblankのサンプルプログラムです。

/server/sendmail.tsx

import * as vtecxapi from 'vtecxapi'

const mailentry = {
    'entry': {
        'title': 'sendmail テスト',
        'summary': 'hello text mail',
        'content': {
            '______text': '<html><body>hello html mail <img src="CID:/_html/img/ajax-loader.gif"></body></html>'
        }
    }
}

const to = ['xxxx@xxx']
const cc = ['xxxx@xxx']
const bcc = ['xxxx@xxx']
const attachments = ['/_html/img/vtec_logo.png']

vtecxapi.sendMail(mailentry, to, cc, bcc, attachments)

これを実行するには、あらかじめpropertiesにメール送信のための設定を行う必要があります。/_settings/properties.xmlに直接記述するか管理画面の「メール|詳細設定」から設定してください。

送信元の指定方法

_mail.from={送信元アドレス}
_mail.from.personal={送信者名}
_mail.password={認証アカウントのパスワード}
_mail.transport.protocol={送信プロトコル}   // "smtp"または"smtps"(Gmailはこちら)。デフォルトは"smtp"。
_mail.smtp.host={SMTPサーバ}
_mail.smtp.port={SMTPポート番号}
_mail.smtp.auth={認証する場合true(デフォルトはtrue)}
_mail.smtp.starttls.enable={STARTTLSを利用する場合true(デフォルトはtrue)}

以下はgmailで送信するための設定例です。

_mail.from=foo@gmail.com
_mail.from.personal=foo
_mail.password=xxx
_mail.transport.protocol=smtps
_mail.smtp.host=smtp.gmail.com
_mail.smtp.port=587
_mail.smtp.auth=true

認証付きリンク

送信するメール本文(テキストメールおよびHTMLメール)に以下の文字列が設定されている場合に認証トークンに変換します。例えば、メールの本文に${RXID=Key}を挿入することで、RXIDを含むURLが自動的に組み立てられます。RXIDは送信先のアカウントのものが生成されます。Keyにはコンテキストパスまで自動的に付加されるためそれ以降のパスを指定してください。

• ${URL} : URLに変換
• ${RXID=/Key} : キーと送信先メールアドレスのRXIDをつけたURLを組み立てて変換
• ${LINK=/Key} : キーと送信先メールアドレスのリンクトークンをつけたURLを組み立てて変換

挿入文: ${RXID=/setpass.html}&value=abc
実際のメール本文: https://test.vte.cx/setpass.html?_RXID=xxx&value=abc

また、変換に際して以下のようなルールがあります。

• 変換は送信先が1件の場合のみ。送信先を複数指定している場合はブランクに変換さる
• 送信先メールアドレスがそのサービスでユーザ登録されていない場合はブランクに変換される。(※正確にはメールアドレスからアカウント使用可能文字だけ取り出し、アカウントを検索しています）
• キー指定部分(/Key)に#が設定されている場合は送信先ユーザのUIDに変換される。

メール受信

vtecxapi.getMail(settings)によりメールを受信することができます。受信結果はfeedのentryに格納されます。複数件受信すると複数件のentryが返ります。
feed.entryの各項目には以下のようにメールの情報がセットされます。()が対応するメールの情報

• title(subject)
• subtitle(cc)
• summary(メール本文)
• content(添付ファイル) ※ Base64に変換されます
  • content.type(ファイルの形式)
  • content.src(ファイル名)

vtecxblankのmail受信サンプル(/server/getmail.js)では、/s/getmailにアクセスすると、Yahoo!メールの設定情報を元にメールを受信します。
vtecxapi.getMail(settings)のsettingsパラメータにはメール受信のための設定を入れます。

mail受信サンプル(/server/getmail.js)

import * as vtecxapi from 'vtecxapi'

const settings: { [index: string]: string } = {}

// 基本設定(例：yahooメール)
settings['mail.pop3.host'] = 'pop.mail.yahoo.co.jp'
settings['mail.pop3.port'] = '995'
// タイムアウト設定
settings['mail.pop3.connectiontimeout'] = '60000'
//SSL関連設定
settings['mail.pop3.socketFactory.class'] = 'javax.net.ssl.SSLSocketFactory'
settings['mail.pop3.socketFactory.fallback'] = 'false'
settings['mail.pop3.socketFactory.port'] = '995'

settings['username'] = 'xxxxx@yahoo.co.jp'
settings['password'] = 'xxxxx'

const result = vtecxapi.getMail(settings)
vtecxapi.log(JSON.stringify(result))

BigQuery連携

vtecxapi.postBQ(request,async,tablenames?)によりBiqQueryにデータを登録することができます。(※ BigQuery連携を使うには事前に設定が必要です。詳しくは、システムフォルダと各種設定を参照してください)
requestはエントリスキーマで定義されたJSONオブジェクトになります。第一階層の項目名がテーブル名に対応します。tablenamesに第一階層の項目名とテーブル名を指定することで異なる名前をテーブル名に指定することができます。tablenamesには、tablanames['{エンティティの第一階層名}']='{Bigqueryテーブル名}' を指定します。例えば、エンティティの第一階層名がfooでテーブル名がbarの場合、const tablenames = { foo : 'bar' }になります。BigQueryのスキーマはエントリスキーマから自動的に作成されるため定義する必要はありません。
エントリスキーマ以外では、key (STRING)、updated (DATETIME)、deleted (BOOL)項目が自動的に登録されます。

vtecxapi.deleteBQ(keys,async,tablenames?)により、BigQueryのデータを削除することができます。これは論理削除であり、実際にはdeletedがtrueのレコードが登録されます。

vtecxapi.getBQ(sql,parent)で登録したデータをJSONとして取得できます。sqlにはBigQueryにおいて実行できるSQL文を指定してください。
また、doResponseBQcsv(sql,filename,header?)により、csvとしてダウンロードできます。
データの更新はなく常に追記される形になるため、sqlでは同じkeyでupdatedが最新かつdeletedがfalseのものを取得するようにしてください。
以下にサンプルコードを示します。

    import * as vtecxapi from 'vtecxapi'

    const reqdata = {
        'feed': {
            'entry': [{
                'foo': { 'bar': 'test', 'baz': 'テスト' },
                'link':
                [{ '___rel': 'self', '___href': '/footest/1' }]
            }
            ]
        }
    }
    
    vtecxapi.postBQ(reqdata,false)    

    // 最新のレコードのみ取得
    const sql = 'select f.key,bar,baz,k.updated from my_dataset.foo as f right join (select key,max(updated) as updated from my_dataset.foo group by key) as k on f.updated=k.updated and f.key=k.key where f.deleted = false'
    const result = vtecxapi.getBQ(sql)
    vtecxapi.log(JSON.stringify(result))
        
    const keys = ['/footest/1']
    vtecxapi.deleteBQ(keys,true)    
    

ちなみに、エントリスキーマ(/_settings/template)は以下の通りです。これがBigQueryのスキーマとしても使われます。(テーブル=foo、項目=bar,baz)

foo
 bar
 baz

バッチジョブ

サーバサイドJavaScriptをバックグラウンドで実行したい場合にはバッチジョブ機能が使えます。バッチジョブ機能は対象サービスのプロパティ(/_settings/propertiesエントリーのrights)に以下を設定することで動作させることができます。

_batchjob.{ジョブ名}={分} {時} {日} {月} {曜日} {サーバサイドJS名}

• {ジョブ名}はサービス内で一意とする。(重複分のジョブは取得されず実行されない。)
• {分} {時} {日} {月} {曜日}の部分はlinuxのcrontabコマンドと同じ指定方法。
• {サーバサイドJS名}はリクエストで/s/の後に指定する値。(/_html/server/、.jsを含まない。)

以下は毎朝8:30にメール送信するサーバサイドJS(/server/send-mail.js)を実行する設定の例です。

_batchjob.sendmail=30 8 * * * send-mail

バッチジョブ管理テーブルを参照することでバッチジョブの実行結果を確認できます。これはジョブの実行ごとに登録されるため、ジョブの実行ステータスを記録するログとして扱うことができます。

• /_batchjob/{ジョブ名}/{ジョブ実行時刻(yyyyMMddHHmm)}のエントリ
• 上記エントリのtitleにジョブ実行ステータス
• subtitleにPod名

ジョブ管理ステータス

• waiting : 実行待ち
• running : 実行中
• succeeded : 成功
• failed : 失敗

waiting(実行待ち)のバッチジョブはプロパティの設定を削除することでキャンセルできますが、running(実行中)のバッチジョブはキャンセルできません。

サーバサイドJSタイムアウト設定

対象サービスのプロパティ(/_settings/propertiesエントリーのrights)に以下を設定することで各サービスにおけるサーバサイドJSのタイムアウト設定ができます。ただしこの設定はproductionサービスのみ有効となります。stagingサービスや設定がない場合などではデフォルトの値(300秒)が採用されます。

• APサーバからの実行の場合: _javascript.exectimeout={タイムアウト秒}
• バッチジョブ実行の場合: _javascript.batchjobtimeout={タイムアウト秒}

vtecxapiメソッド一覧

vtecxapiのメソッドには以下のようなものがあります。

リクエスト情報取得

データ操作

他サイトへのアクセス

採番

採番カウンタ操作

レスポンス関連

ログ

PDF、XLS出力

メール送受信

セッション関連

ページネーション

BigQuery連携

PDFスタイルシート

ページ構造

PDFのページは以下のように３つのレベル要素により構成されます。
第一レベル要素はすべて左下点を基準とする絶対座標で指定することができます。
第二レベル要素は第一レベル要素からの相対位置座標となります。

• 基底要素
  • htmlタグ：<html>
  • bodyタグ：<body>
  • ページタグ：<div class="_page">
• 第一レベル要素
  • テーブル：<table> <tr> <td>
    • 注：<table>の子要素に<table>を指定することはできません。
  • イメージ：<img>
  • 図形：<div class="_rectangle">、<div class="_line">
• 第二レベル要素
  • ブロックレベル要素：<div>、<p>
    • リスト：<ul>、<ol>
  • インライン要素：<span>
    • リンク：<a>
    • イメージ：<img>
    • 改行：<br>

pageタグ

<div class="_page">タグ（以下、pageタグとします）には、ページの大きさや向き、余白サイズ、暗号化や署名などを設定できます。styleで指定できる属性には以下のものがあります。

<table>タグ

<table>タグにより表を作ることができます。これは、行(<tr>)と列(<td>もしくは<th>)を子要素にもちます。style属性には以下を指定することができます。

<tr>タグ

style属性には以下を指定できます。

<td>タグ

style属性には以下を指定できます。

文字列の表示

文字列を表示する場合、<p>,<div>,<span>のいずれかのタグを使用します。
上記タグで囲まなければ、デフォルトを含むレイアウト表示はされませんのでご注意ください。
<p>,<div>タグの場合、文字列表示の後に改行されます。<span>タグの場合改行されません。style属性には以下を指定できます。

改行

改行は<br/>タグを使用します。(必ず最後にスラッシュを入れて閉じてください)

リンク

リンクは<a>タグを使用します。href属性にリンク先URLを指定してください。
<a>タグに囲む文字列は、<p>,<div>,<span>のいずれかで囲んでください。

リスト

リストは<ul>、<ol>、<li>タグを使用します。
<li>タグに囲む文字列は、<p>,<div>,<span>のいずれかで囲んでレイアウトを編集してください。シンボルは<ul>、<ol>タグでレイアウト編集できます。style属性には以下を指定できます。

画像

画像は<img>タグを使用します。src属性に画像のurl、width属性に画像の幅、height属性に画像の高さを指定してください。style属性には以下を指定できます。

線

<div class="_line">で線を描画します。style属性には以下を指定できます。

四角形

<div class="_rectangle">で四角形を描画します。style属性には以下を指定できます。

角丸四角形

<div class="_roundrectangle">で四角形を描画します。style属性には以下を指定できます。

円

<div class="_circle">で円を描画します。style属性には以下を指定できます。

バーコードJAN(EAN、UPC)規格

<div class="_barcodeEAN">でJAN(EAN、UPC)規格のバーコードを描画します。style属性には以下を指定できます。

バーコードNW-7（CODABAR）規格

<div class="_barcodeNW7">でNW-7（CODABAR）規格のバーコードを描画します。style属性には以下を指定できます。

バーコードcode39規格

<div class="_barcode39">でcode39規格のバーコードを描画します。style属性には以下を指定できます。

バーコードcode128規格

<div class="_barcode128">でcode128規格のバーコードを描画します。style属性には以下を指定できます。

QRコード

<div class="_qrcode">でQRコードを描画します。style属性には以下を指定できます。

HTTPステータスとメッセージ

400エラー詳細

401エラー詳細

409エラー詳細