diff options
| -rw-r--r-- | docs/ja/api_development_environment.md | 8 | ||||
| -rw-r--r-- | docs/ja/api_development_overview.md | 49 | ||||
| -rw-r--r-- | docs/ja/api_docs.md | 73 | ||||
| -rw-r--r-- | docs/ja/api_overview.md | 20 |
4 files changed, 150 insertions, 0 deletions
diff --git a/docs/ja/api_development_environment.md b/docs/ja/api_development_environment.md new file mode 100644 index 0000000000..8dce1ba2fd --- /dev/null +++ b/docs/ja/api_development_environment.md @@ -0,0 +1,8 @@ +# 開発環境のセットアップ + +<!--- + original document: 0.9.50:docs/api_development_environment.md + git diff 0.9.50 HEAD -- docs/api_development_environment.md | cat +--> + +開発環境をセットアップするには、[qmk_web_stack](https://github.com/qmk/qmk_web_stack) に行ってください。 diff --git a/docs/ja/api_development_overview.md b/docs/ja/api_development_overview.md new file mode 100644 index 0000000000..0612507b4d --- /dev/null +++ b/docs/ja/api_development_overview.md @@ -0,0 +1,49 @@ +# QMK コンパイラ開発ガイド + +<!--- + original document: 0.9.50:docs/api_development_overview.md + git diff 0.9.50 HEAD -- docs/api_development_overview.md | cat +--> + +このページでは、開発者に QMK コンパイラを紹介しようと思います。コードを読まなければならないような核心となる詳細に立ち入って調べることはしません。ここで得られるものは、コードを読んで理解を深めるためのフレームワークです。 + +# 概要 + +QMK Compile API は、いくつかの可動部分からできています: + + + +API クライアントは API サービスと排他的にやりとりをします。ここでジョブをサブミットし、状態を調べ、結果をダウンロードします。API サービスはコンパイルジョブを [Redis Queue](https://python-rq.org) に挿入し、それらのジョブの結果について RQ と S3 の両方を調べます。 + +ワーカーは RQ から新しいコンパイルジョブを取り出し、ソースとバイナリを S3 互換のストレージエンジンにアップロードします。 + +# ワーカー + +QMK コンパイラワーカーは実際のビルド作業に責任を持ちます。ワーカーは RQ からジョブを取り出し、ジョブを完了するためにいくつかの事を行います: + +* 新しい qmk_firmware のチェックアウトを作成する +* 指定されたレイヤーとキーボードメタデータを使って `keymap.c` をビルドする +* ファームウェアをビルドする +* ソースのコピーを zip 形式で圧縮する +* ファームウェア、ソースの zip ファイル、メタデータファイルを S3 にアップロードする +* ジョブの状態を RQ に送信する + +# API サービス + +API サービスは比較的単純な Flask アプリケーションです。理解しておくべきことが幾つかあります。 + +## @app.route('/v1/compile', methods=['POST']) + +これは API の主なエントリーポイントです。クライアントとのやりとりはここから開始されます。クライアントはキーボードを表す JSON ドキュメントを POST し、API はコンパイルジョブをサブミットする前にいくらかの(とても)基本的な検証を行います。 + +## @app.route('/v1/compile/<string:job_id>', methods=['GET']) + +これは最もよく呼ばれるエンドポイントです。ジョブの詳細が redis から利用可能であればそれを取り出し、そうでなければ S3 からキャッシュされたジョブの詳細を取り出します。 + +## @app.route('/v1/compile/<string:job_id>/download', methods=['GET']) + +このメソッドによりユーザはコンパイルされたファームウェアファイルをダウンロードすることができます。 + +## @app.route('/v1/compile/<string:job_id>/source', methods=['GET']) + +このメソッドによりユーザはファームウェアのソースをダウンロードすることができます。 diff --git a/docs/ja/api_docs.md b/docs/ja/api_docs.md new file mode 100644 index 0000000000..b483c045e6 --- /dev/null +++ b/docs/ja/api_docs.md @@ -0,0 +1,73 @@ +# QMK API + +<!--- + original document: 0.9.50:docs/api_docs.md + git diff 0.9.50 HEAD -- docs/api_docs.md | cat +--> + +このページは QMK API の使い方を説明します。もしあなたがアプリケーション開発者であれば、全ての [QMK](https://qmk.fm) キーボードのファームウェアをコンパイルするために、この API を使うことができます。 + +## 概要 + +このサービスは、カスタムキーマップをコンパイルするための非同期 API です。API に 何らかの JSON を POST し、定期的に状態をチェックし、ファームウェアのコンパイルが完了していれば、結果のファームウェアと(もし希望すれば)そのファームウェアのソースコードをダウンロードすることができます。 + +#### JSON ペイロードの例: + +```json +{ + "keyboard": "clueboard/66/rev2", + "keymap": "my_awesome_keymap", + "layout": "LAYOUT_all", + "layers": [ + ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"], + ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"], + ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"] + ] +} +``` + +ご覧のとおり、ペイロードにはファームウェアを作成および生成するために必要なキーボードの全ての側面を記述します。各レイヤーは QMK キーコードの1つのリストで、キーボードの `LAYOUT` マクロと同じ長さです。もしキーボードが複数の `LAYOUT` マクロをサポートする場合、どのマクロを使うかを指定することができます。 + +## コンパイルジョブのサブミット + +キーマップをファームウェアにコンパイルするには、単純に JSON を `/v1/compile` エンドポイントに POST します。以下の例では、JSON ペイロードを `json_data` という名前のファイルに配置しています。 + +``` +$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile +{ + "enqueued": true, + "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6" +} +``` + +## 状態のチェック + +キーマップをサブミットした後で、簡単な HTTP GET 呼び出しを使って状態をチェックすることができます: + +``` +$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6 +{ + "created_at": "Sat, 19 Aug 2017 21:39:12 GMT", + "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT", + "id": "f5f9b992-73b4-479b-8236-df1deb37c163", + "status": "running", + "result": null +} +``` + +これは、ジョブをキューに入れることに成功し、現在実行中であることを示しています。5つの状態がありえます: + +* **failed**: なんらかの理由でコンパイルサービスが失敗しました。 +* **finished**: コンパイルが完了し、結果を見るには `result` をチェックする必要があります。 +* **queued**: キーマップはコンパイルサーバが利用可能になるのを待っています。 +* **running**: コンパイルが進行中で、まもなく完了するはずです。 +* **unknown**: 深刻なエラーが発生し、[バグを報告](https://github.com/qmk/qmk_compiler/issues)する必要があります。 + +## 完了した結果を検証 + +コンパイルジョブが完了したら、`result` キーをチェックします。このキーの値は幾つかの情報を含むハッシュです: + +* `firmware_binary_url`: 書き込み可能なファームウェアの URL のリスト +* `firmware_keymap_url`: `keymap.c` の URL のリスト +* `firmware_source_url`: ファームウェアの完全なソースコードの URL のリスト +* `output`: このコンパイルジョブの stdout と stderr。エラーはここで見つけることができます。 diff --git a/docs/ja/api_overview.md b/docs/ja/api_overview.md new file mode 100644 index 0000000000..18b8eae10f --- /dev/null +++ b/docs/ja/api_overview.md @@ -0,0 +1,20 @@ +# QMK API + +<!--- + original document: 0.9.50:docs/api_overview.md + git diff 0.9.50 HEAD -- docs/api_overview.md | cat +--> + +QMK API は、Web と GUI ツールが [QMK](http://qmk.fm/) によってサポートされるキーボード用の任意のキーマップをコンパイルするために使うことができる、非同期 API を提供します。標準のキーマップテンプレートは、C コードのサポートを必要としない全ての QMK キーコードをサポートします。キーボードのメンテナは独自のカスタムテンプレートを提供して、より多くの機能を実現することができます。 + +## アプリケーション開発者 + +もしあなたがアプリケーションでこの API を使うことに興味があるアプリケーション開発者であれば、[API の使用](ja/api_docs.md) に行くべきです。 + +## キーボードのメンテナ + +もし QMK Compiler API でのあなたのキーボードのサポートを強化したい場合は、[キーボードサポート](ja/reference_configurator_support.md) の節に行くべきです。 + +## バックエンド開発者 + +もし API 自体に取り組むことに興味がある場合は、[開発環境](ja/api_development_environment.md)のセットアップから始め、それから [API のハッキング](ja/api_development_overview.md) を調べるべきです。 |