chore: add Japanese README and advanced config doc (#306)

momentohq · Oct 14, 2022 · 4559c2f · 4559c2f
1 parent 3cfbb4f
commit 4559c2f
Show file tree

Hide file tree

Showing 3 changed files with 230 additions and 17 deletions.
diff --git a/README.ja.md b/README.ja.md
@@ -0,0 +1,164 @@
+<head>
+  <meta name="Momento .NET Client Library Documentation" content=".NET client software development kit for Momento Serverless Cache">
+</head>
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+[![project status](https://momentohq.github.io/standards-and-practices/badges/project-status-official.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
+[![project stability](https://momentohq.github.io/standards-and-practices/badges/project-stability-beta.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
+
+# Momento .NET Client Library
+
+:warning: Beta SDK :warning:
+
+こちらの SDK は Momento の公式 SDK ですが、API は Beta ステージです。詳細は上記の Beta ボタンをクリックしてください。
+
+Momento Serverless Cache の .NET クライアント SDK：従来のキャッシュが必要とするオペレーションオーバーヘッドが全く無く、速くて、シンプルで、従量課金のキャッシュです！
+
+## さあ、使用開始 :running:
+
+### 必要条件
+
+[`dotnet` runtime そしてコマンドラインツール](https://dotnet.microsoft.com/en-us/download)が必要です。インストール後は PATH に`dotnet`のコマンドがある事を確認してください。
+
+**IDE に関する注意事項**: [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs), [JetBrains Rider](https://www.jetbrains.com/rider/)や[Microsoft Visual Studio Code](https://code.visualstudio.com/)の様な .NET 開発をサポートできる IDE が必要となります。
+
+### 使用方法
+
+使用開始の準備万全ですか？ではこちらの[examples](./examples/README.md)ディレクトリを参照してください！
+
+### Momento レスポンスタイプ
+
+Momento の`SimpleCacheClient`クラスの戻り値は IDE が容易にエラーを含む、有り得るレスポンスを予測できる様にデザインしてあります。[パターンマッチング](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching)を使用し、様々なレスポンスタイプを区別します。そうすることで、それらの API を使用する時、ランタイムでバグを発見するよりも、コンパイル時での安全性があります。
+
+以下が使用例です:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+  Console.WriteLine($"Looked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+}
+else if (getResponse is CacheGetResponse.Error getError)
+{
+  Console.WriteLine($"Error getting value: {getError.Message}");
+}
+```
+
+詳細は下記にある[エラーの対処法](#エラーの処理法)を参照してください。
+
+### インストール
+
+新規に.NET プロジェクトを作成し、Momento client library を dependency として追加してください：
+
+```bash
+mkdir my-momento-dotnet-project
+cd my-momento-dotnet-project
+dotnet new console
+dotnet add package Momento.Sdk
+```
+
+### 使用方法
+
+以下がご自身のプロジェクトに使用できるクイックスタートです：
+
+```csharp
+using System;
+using Momento.Sdk;
+using Momento.Sdk.Auth;
+using Momento.Sdk.Config;
+using Momento.Sdk.Responses;
+
+ICredentialProvider authProvider = new EnvMomentoTokenProvider("MOMENTO_AUTH_TOKEN");
+const string CACHE_NAME = "cache";
+const string KEY = "MyKey";
+const string VALUE = "MyData";
+TimeSpan DEFAULT_TTL = TimeSpan.FromSeconds(60);
+
+using (SimpleCacheClient client = new SimpleCacheClient(Configurations.Laptop.Latest(), authProvider, DEFAULT_TTL))
+{
+    var createCacheResponse = await client.CreateCacheAsync(CACHE_NAME);
+    if (createCacheResponse is CreateCacheResponse.Error createError)
+    {
+        Console.WriteLine($"Error creating cache: {createError.Message}. Exiting.");
+        Environment.Exit(1);
+    }
+
+    Console.WriteLine($"Setting key: {KEY} with value: {VALUE}");
+    var setResponse = await client.SetAsync(CACHE_NAME, KEY, VALUE);
+    if (setResponse is CacheSetResponse.Error setError)
+    {
+        Console.WriteLine($"Error setting value: {setError.Message}. Exiting.");
+        Environment.Exit(1);
+    }
+
+    Console.WriteLine($"Get value for key: {KEY}");
+    CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+    if (getResponse is CacheGetResponse.Hit hitResponse)
+    {
+        Console.WriteLine($"Looked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+    }
+    else if (getResponse is CacheGetResponse.Error getError)
+    {
+        Console.WriteLine($"Error getting value: {getError.Message}");
+    }
+}
+
+```
+
+上記のコードは MOMENTO_AUTH_TOKEN という環境変数が必要です。またこの値は有効な[Momento オーセンティケーショントークン](https://docs.momentohq.com/docs/getting-started#obtain-an-auth-token)でなければなりません。
+
+### エラーの処理法
+
+従来の例外処理とは異なり、SimpleCacheClient のメソッドを呼び出した際に起こるエラーは戻り値として浮上します。こうすることで、エラーの可視化を行い、必要なエラーのみを処理する際に IDE が更に役立つ様になります。（もっと例外についての私達の哲学を知りたい方はこちらの[例外はバグだ](https://www.gomomento.com/blog/exceptions-are-bugs)をぜひお読みください。またフィードバックもお待ちしております！）
+
+SimpleCacheClient メソッドからの戻り値の好ましい対応の仕方は[パターンマッチング](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching)を使用する方法です。こちらが簡単な例です：
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+    Console.WriteLine($"\nLooked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+} else {
+      // `else if`内でパターンマッチングを使用し、他のケースも対処可能です。
+      // またデフォルトのケースであれば`else`ブロックで対処可能です。
+      // 各戻り値に対して、IDE上で有り得るタイプを提案してくれるはずです。
+      // この場合だと`CacheGetResponse.Miss`と `CacheGetResponse.Error`です。
+}
+```
+
+こちらのアプローチだと、キャッシュヒットの場合タイプが保証された`hitResponse`オブジェクトを受け取ります。キャッシュ読み込みの結果がミスもしくはエラーの場合でも何が起こったかの詳細な情報を含み、タイプの保証されたオブジェクトを受け取ることができます。
+
+エラーのレスポンスを受け取った場合、`Error`タイプはエラータイプを確認できる`ErrorCode` をいつも含んでいます：
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Error errorResponse)
+{
+    if (errorResponse.ErrorCode == MomentoErrorCode.TIMEOUT_ERROR) {
+       // こちらはクライアント側のタイムアウト意味しており、これが起こった場合元のデータを使用する事が可能です。
+    }
+}
+```
+
+SimpleCacheClient の戻り値以外では例外が起こる可能性があり、それらは通常通り処理する必要があるのでご注意ください。
+例えば、SimpleCacheClient のインスタンスを生成する際、無効なオーセンティケーショントークンは IllegalArgumentException の発生原因になります。
+
+### チューニング
+
+Momento client-libraries はあらかじめ用意されたコンフィグがすぐに使用できるようになっています。お客さまがビジネスにフォーカスできるよう、様々な環境に適したチューニングを私達の方で担いたいと思っています。
+(ブログシリーズも存在ます！ [ショックなほどシンプル: 大変な作業を担ってくれるキャッシュクライアント](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
+
+`Configurations`ネームスペースにてあらかじめ用意されたコンフィグを確認していただけます。以下がそれらのコンフィグになります：
+
+- `Configurations.Laptop` - こちらは開発環境に適しており、Momento の使用テストを行いたい場合に最適です。タイムアウトは緩く設定されているので、ネットワークレイテンシーは少し高くなる事が予想されます。
+- `Configurations.InRegion.Default` - こちらはご自身のクライアントが Momento と同じリージョンで実行されている場合に最適なデフォルト設置です。タイムアウトとリトライは Laptop 設定よりも厳しく設定してあります。
+- `Configurations.InRegion.LowLatency` - こちらの設定は p99.9 のレイテンシを最優先しており、そのためスループットが低くなる場合があります。こちらの設定はキャッシュの不可用性が高いレイテンシーを起こしたくない場合に使用してください。
+
+これらのコンフィグが大半のお客様のニーズにお応えできると思いますが、不足している部分などありましたらお気軽に GitHub でチケット作成または`[email protected]`にご連絡ください。お客様の使用例を聞いて、より優れたコンフィグを提供したいと考えております。
+
+あらかじめ用意されたコンフィグ以外にカスタムのコンフィグを作成されたい場合はこちらの
+[上級者レベルコンフィグガイド](./docs/advanced-config.md)をご覧ください。
+
+---
+
+更なる詳細は私達のウェブサイト[https://jp.gomomento.com/](https://jp.gomomento.com/)をご確認ください！
diff --git a/README.template.md b/README.template.md
@@ -1,22 +1,24 @@
 {{ ossHeader }}
 
+Japanese: [日本語](README.ja.md)
+
 ## Getting Started :running:
 
 ### Requirements
 
-You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download).  After installing them, you should have the `dotnet` command on your PATH.
+You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download). After installing them, you should have the `dotnet` command on your PATH.
 
 **IDE Notes**: You will most likely want an IDE that supports .NET development, such as [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs), [JetBrains Rider](https://www.jetbrains.com/rider/), or [Microsoft Visual Studio Code](https://code.visualstudio.com/).
 
 ### Examples
 
-Ready to dive right in?  Just check out the [examples](./examples/README.md) directory for complete, working examples of
+Ready to dive right in? Just check out the [examples](./examples/README.md) directory for complete, working examples of
 how to use the SDK.
 
 ### Momento Response Types
 
 The return values of the methods on the Momento `SimpleCacheClient` class are designed to allow you to use your
-IDE to help you easily discover all the possible responses, including errors.  We use [pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching) to distinguish between different types of responses,
+IDE to help you easily discover all the possible responses, including errors. We use [pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching) to distinguish between different types of responses,
 which means that you can get compile-time safety when interacting with the API, rather than having bugs sneak in at runtime.
 
 Here's an example:
@@ -60,12 +62,12 @@ be set to a valid [Momento authentication token](https://docs.momentohq.com/docs
 ### Error Handling
 
 Error that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
-the calls, as opposed to by throwing exceptions.  This makes them more visible, and allows your IDE to be more
-helpful in ensuring that you've handled the ones you care about.  (For more on our philosophy about this, see our
-blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs).  And send us any
+the calls, as opposed to by throwing exceptions. This makes them more visible, and allows your IDE to be more
+helpful in ensuring that you've handled the ones you care about. (For more on our philosophy about this, see our
+blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs). And send us any
 feedback you have!)
 
-The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching).  Here's a quick example:
+The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching). Here's a quick example:
 
 ```csharp
 CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
@@ -80,7 +82,7 @@ if (getResponse is CacheGetResponse.Hit hitResponse)
 }
 ```
 
-Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit.  But if the cache read
+Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit. But if the cache read
 results in a Miss or an error, you'll also get a type-safe object that you can use to get more info about what happened.
 
 In cases where you get an error response, `Error` types will always include an `ErrorCode` that you can use to check
@@ -101,23 +103,23 @@ to instantiate a SimpleCacheClient with an invalid authentication token will res
 
 ### Tuning
 
-Momento client-libraries provide pre-built configuration bundles out-of-the-box.  We want to do the hard work of
+Momento client-libraries provide pre-built configuration bundles out-of-the-box. We want to do the hard work of
 tuning for different environments for you, so that you can focus on the things that are unique to your business.
-(We even have a blog series about it!  [Shockingly simple: Cache clients that do the hard work for you](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
+(We even have a blog series about it! [Shockingly simple: Cache clients that do the hard work for you](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
 
-You can find the pre-built configurations in our `Configurations` namespace.  Some of the pre-built configurations that
+You can find the pre-built configurations in our `Configurations` namespace. Some of the pre-built configurations that
 you might be interested in:
 
-- `Configurations.Laptop` - this one is a development environment, just for poking around.  It has relaxed timeouts
-      and assumes that your network latencies might be a bit high.
+- `Configurations.Laptop` - this one is a development environment, just for poking around. It has relaxed timeouts
+  and assumes that your network latencies might be a bit high.
 - `Configurations.InRegion.Default` - provides defaults suitable for an environment where your client is running in the same region as the Momento
-      service.  It has more aggressive timeouts and retry behavior than the Laptop config.
+  service. It has more aggressive timeouts and retry behavior than the Laptop config.
 - `Configurations.InRegion.LowLatency` - This config prioritizes keeping p99.9 latencies as low as possible, potentially sacrificing
-      some throughput to achieve this.  Use this configuration if the most important factor is to ensure that cache
-      unavailability doesn't force unacceptably high latencies for your own application.
+  some throughput to achieve this. Use this configuration if the most important factor is to ensure that cache
+  unavailability doesn't force unacceptably high latencies for your own application.
 
 We hope that these configurations will meet the needs of most users, but if you find them lacking in any way, please
-open a github issue, or contact us at `[email protected]`.  We would love to hear about your use case so that we
+open a github issue, or contact us at `[email protected]`. We would love to hear about your use case so that we
 can fix or extend the pre-built configs to support it.
 
 If you do need to customize your configuration beyond what our pre-builts provide, see the

diff --git a/docs/advanced-config.ja.md b/docs/advanced-config.ja.md
@@ -0,0 +1,47 @@
+<head>
+  <meta name="Momento .NET Client Library Documentation" content=".NET client software development kit for Momento Serverless Cache">
+</head>
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+# Momento .NET Client Library: 上級者レベルコンフィグ
+
+## クライアントタイムアウトの変更
+
+もしクライアントサイドのタイムアウトが唯一の設定であれば、あらかじめ用意されているコンフィグと共に `WithClientTimeout`のメソッドを使用して設定できます：
+
+```csharp
+new SimpleCacheClient(
+    Configurations.InRegion.Default.Latest().WithClientTimeout(TimeSpan.FromSeconds(2))
+)
+```
+
+## カスタムコンフィグ
+
+ほとんどの場合はあらかじめ用意されているコンフィグで間に合うかと思います。しかし、もしこれらのデフォルト設定を上書きしたい場合は、`IConfiguration`インターフェイスを実装するご自身のコンフィグオブジェクトが作成可能です。
+
+一番簡単な方法は、`Configuration`クラスを使用する事です。こちらのクラスは４つの引数を受け取ります：
+
+```csharp
+new Configuration(loggerFactory, retryStrategy, middlewares, transportStrategy)
+```
+
+あらかじめ用意されたコンフィグがどの様に構成されているのかは[Configurations.cs](../src/Momento.Sdk/Config/Configurations.cs)にあるソースコードをご確認ください。カスタムコンフィグを作成するのに良い例が記載されています。
+
+以下は各引数に関する詳細です。
+
+### loggerFactory
+
+これは.NET の`ILoggerFactory`のインスタンスです。これは`IConfiguration`を実装する全ての Momento クラスに対するログをコンフィグします。
+
+### retryStrategy
+
+失敗したリクエストがリトライされるのか、またどの様にリトライされるのかを管理します。この引数のインターフェースは`IRetryStrategy`です。`FixedCountRetryStrategy`の様なシンプルなあらかじめ用意したものがありますが、カスタムのリトライ動作を作成するために、このインターフェースをご自身で実装していただけます。
+
+### middlewares
+
+この引数に対して０もしくはそれ以上の`IMiddleware`インスタンスを渡すことができます。こちらはリクエストやレスポンスのインターセプタとして機能します。こちらはデバッグのログやパフォーマンスの情報収集など、様々なケースに使用していただけます。シンプルな例は `LoggingMiddleware`を参照してください。
+
+### transportStrategy
+
+こちらは Momento サービスとのコミュニケーションに対する低レベルのネットワーキングの設定をコンフィグします。
+詳細は`ITransportStrategy`インターフェイスを参照してください。