ローカルストレージ

このガイドでは、cTraderアルゴリズムを開発する際にローカルストレージをどのように扱うかについて説明します。以下に、ローカルストレージへのアクセスがどのように機能するかを1分でまとめました。

1分でわかるローカルストレージ！

ローカルストレージを使用すると、ローカルファイルシステムに情報を保存できます。 cBotやインジケーターの2回以上のデプロイメント間でデータを永続化するために使用します。
データを保存するには、SetString(string key, string value)およびSetObject(string key, object obj)メソッドを使用します。データを取得するには、GetString(string key)およびT GetObject<T>(string key)メソッドを呼び出します。
LocalStorageScope列挙型を使用して、希望するローカルストレージのスコープを指定します。例えば、SetString(string key, string value, LocalStorageScope.Device)オーバーロードは、Documents/cAlgo/LocalStorage/ディレクトリにデータを保存します。
情報は毎分自動的に保存されますが、Flush(LocalStorageScope localStorageScope)メソッドを使用して遅延なくデータを保存することもできます。
バックテストと最適化中、ローカルストレージはメモリ内にのみデータを保存します。

ローカルストレージの使用

ローカルストレージは、cBotやインジケーターの1回または複数回の停止と開始の間で情報を保存する方法として考えてください。この機能により、cBotやインジケーターのデータを保存し、その後、必要に応じてこの情報にアクセスすることができます。ローカルストレージは、アルゴリズムに与えられたアクセス権限に関係なく機能します。

LocalStorageインターフェースには、ローカルストレージにデータを保存およびアクセスするために使用できるすべてのメソッドが含まれています。これらのメソッドの例には、以下が含まれます：

SetString(string key, string value) - 指定されたキーに一致する文字列値を保存します。
SetObject(string key, object obj) - 指定されたキーに一致するオブジェクトを保存します。
GetString(string key) - 指定されたキーの下にある保存された文字列値を取得します。
T GetObject<T>(string key) - 指定されたキーの下にある保存された型Tのオブジェクトをローカルストレージから取得します。

警告

SetObject(string key, object obj)およびGetObject<T>(string key)メソッドは、シリアライズ可能な（バイトに変換可能な）データ型でのみ機能します。

以下の例では、cBotインスタンスに起動時に例のメッセージを保存するように要求します。その後、同じインスタンスが起動するたびに、メッセージボックスにメッセージが表示されます。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using cAlgo.API;
using cAlgo.API.Collections;
using cAlgo.API.Indicators;
using cAlgo.API.Internals;

namespace cAlgo.Robots
{
    [Robot(AccessRights = AccessRights.None)]
    public class SampleLocalStorageTest : Robot

    {

        protected override void OnStart()
        {

            string messageLocalStorage = LocalStorage.GetString("Example Message");

            if (messageLocalStorage is not null)

            {

                MessageBox.Show(messageLocalStorage);

            }

            LocalStorage.SetString("Example Message", "This is just an example message");
        }
    }
}

上記のcBotのインスタンスが初めて起動されると、ローカルストレージに例のメッセージが保存されます。インスタンスを停止して再度起動すると、以下のメッセージボックスが表示されます。

AccessRights.Noneが指定されている場合でも、ローカルストレージが機能することに注意してください。

ローカルストレージのスコープを定義する

ローカルストレージのスコープ（LocalStorageScope型で定義）は、情報がどこに保存され、どのようにアクセスできるかを決定します。このenumには以下の定数が含まれます：

LocalStorageScope.Instance - 保存されたデータは、特定の実行中のcBotまたはインジケーターのインスタンスによってのみ保存およびアクセスできます。情報はDocuments/cAlgo/LocalStorage/{AlgoType}/{AlgoName}/{InstanceUniqueIdentifier}/ディレクトリに保存されます。このパスでは、「AlgoType」はローカルストレージを扱うcTrader拡張機能のタイプ（cBotsまたはIndicators）を示し、AlgoNameは特定のcBot/インジケーターの名前を示します。 InstanceUniqueIdentifierは、特定のcBotまたはインジケーターのインスタンスの一意のIDです。
LocalStorageScope.Type - 保存されたデータは、特定のcBotまたはインジケーターのすべての実行中のインスタンスによって保存およびアクセスできます。情報はDocuments/cAlgo/LocalStorage/{AlgoType}/{AlgoName}/ディレクトリに保存されます。
LocalStorageScope.Device - 保存されたデータは、現在のデバイス上のすべての実行中のcBotおよびインジケーターのインスタンスによって保存およびアクセスできます。情報はDocuments/cAlgo/LocalStorage/ディレクトリに保存されます。

一方、SetString()やSetObject()などのメソッドには、カスタムローカルストレージスコープを指定できる追加のオーバーロードがあります。例えば、以下のコードは文字列をLocalStorageScope.Typeに保存します。この文字列は、その後、特定のタイプのすべての拡張機能からアクセス可能になります。

SetString(“Example String”, “Just an example string”, LocalStorageScope.Type);

LocalStorageScopeがパラメータとして指定されていない場合、デフォルトでLocalStorageScope.Instanceが使用されます。

GetString(string key)およびT GetObject<T>(string key)メソッドの場合、この動作は異なることに注意してください。これらのメソッドがローカルストレージスコープを指定せずに呼び出されると、指定されたキーを以下の階層に従ってすべてのスコープで検索します：

インスタンス
種類
デバイス

さらに、各異なるローカルストレージスコープには独自のディスクスペースのクォータがあります：

LocalStorageScope.Instanceは10 MBに制限されています。
LocalStorageScope.Typeは100 MBに制限されています。
LocalStorageScope.Deviceは500 MBに制限されています。

上記で定義された制限は累積的ではありません。例えば、デバイスレベルのストレージの500 MBをすべて使用した場合でも、インスタンスレベルのストレージを使用して10 MBの制限に達するまで情報を保存することができます。

情報の保存と読み込みの仕組み

ローカルストレージに情報を保存する場合（例えば、SetString()メソッドを呼び出すことによって）、cTraderは毎分自動的にデータを保存します。データはインスタンス停止時にも保存されます。

ただし、以下のメソッドを使用してこの動作をカスタマイズできます：

Flush(LocalStorageScope localStorageScope) - 指定されたスコープにすべてのデータを保存します。
Reload(LocalStorageScope localStorageScope) - 指定されたスコープからすべての値を再読み込みします。

Reload(LocalStorageScope localStorageScopeメソッドを呼び出す際、保留中の変更が失われる可能性があることに注意してください。これを避けるために、事前にFlush(LocalStorageScope localStorageScope)を呼び出すようにしてください。

以下の例では、cBotに成行注文を実行するように要求します。このアクションが完了した後、直ちに開いたポジションの総損益をLocalStorageScope.Typeに保存します。

ExecuteMarketOrder(TradeType.Buy, SymbolName, 10000, “Custom label”);
var positionOne = Positions.Find("Custom label");        
string positionOneGrossProfit = positionOne.GrossProfit.ToString();
LocalStorage.SetString("Position 1", positionOneGrossProfit, LocalStorageScope.Device); 
LocalStorage.Flush(LocalStorageScope.Device);

バックテストと最適化におけるローカルストレージ

ローカルストレージは、バックテストではリアルタイム取引とは異なる動作をします。

前述のように、リアルタイム取引でこの機能を使用する場合、ローカルストレージはローカルマシンのファイルシステムを使用します。しかし、バックテストでファイルシステムを使用すると、現在の市場の動きや取引操作に関係のない大量のデータを保存するなど、いくつかの問題が発生します。

これらの問題を回避するため、バックテストやcBotの最適化を行う際には、ローカルストレージのすべての操作がメモリ内でのみ行われます。その結果、ファイルシステムに保存されるすべてのデータがリアルタイム取引に関連するものであることが保証されます。

要約すると、ローカルストレージはAlgo APIの非常に有益な機能であり、複数のcBotやインジケーターの停止と開始の間でデータを永続化することができます。ローカルストレージを効果的に使用することで、ファイルシステムに保存されたカスタムデータに基づいて複雑な自動取引戦略を作成することができます。