Skip to content

Commit

Permalink
[JA] XRPLF#2340 , and request/response/erro formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@tequdev
tequdev committed May 22, 2024
1 parent 6e1785e commit c63237d
Show file tree
Hide file tree
Showing 5 changed files with 278 additions and 101 deletions.
53 changes: 31 additions & 22 deletions @i18n/ja/docs/references/http-websocket-apis/api-conventions/error-formatting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ html: error-formatting.html
parent: api-conventions.html
seo:
description: WebSocket、JSON-RPC、コマンドラインインターフェイスのエラーフォーマットと汎用エラーコードです。
labels:
- 開発
---
# エラーのフォーマット

Expand All @@ -16,7 +18,7 @@ seo:
{% tabs %}

{% tab label="WebSocket" %}
```
```json
{
"id": 3,
"status": "error",
Expand All @@ -34,8 +36,9 @@ seo:
{% /tab %}

{% tab label="JSON-RPC" %}
```
```json
HTTP Status: 200 OK

{
"result": {
"error": "ledgerIndexMalformed",
Expand All @@ -52,7 +55,7 @@ HTTP Status: 200 OK
{% /tab %}

{% tab label="コマンドライン" %}
```
```json
{
"result": {
"error": "ledgerIndexMalformed",
Expand All @@ -73,18 +76,19 @@ HTTP Status: 200 OK

## WebSocketフォーマット

| `Field` | 型 | 説明 |
|:----------|:---------|:------------------------------------------------------|
| `id` | （場合により異なる） | このレスポンスのリクエスト元となったWeb Socketリクエストに指定されていたID |
| `status` | 文字列 | `"error"`: リクエストが原因でエラーが発生した場合 |
| `type` | 文字列 | 通常は`"response"`。これは、コマンドに対し正常にレスポンスしたことを示します。 |
| `error` | 文字列 | 発生したエラータイプの一意のコード。 |
| `request` | オブジェクト | このエラーが発生したリクエストのコピー（JSONフォーマット）。**注意:** リクエストにアカウントの機密情報が含まれている場合、ここにコピーされます。 |
| `Field` | 型 | 説明 |
|:--------------|:------|:------------------------------------------------------|
| `id` | (多様) | このレスポンスのリクエスト元となったWeb Socketリクエストに指定されていたID |
| `status` | 文字列 | `"error"`: リクエストが原因でエラーが発生した場合 |
| `type` | 文字列 | 通常は`"response"`。これは、コマンドに対し正常にレスポンスしたことを示します。 |
| `error` | 文字列 | 発生したエラータイプの一意のコード。 |
| `request` | オブジェクト | このエラーが発生したリクエストのコピー（JSONフォーマット）。**注意:** リクエストにアカウントの機密情報が含まれている場合、ここにコピーされます。 |
| `api_version` | 数値 | _(省略可)_ リクエストで`api_version`を指定していた場合は、その値。 |


## JSON-RPCフォーマット

一部のJSON-RPCリクエストは、HTTPレイヤーでエラーコードでレスポンスします。この場合、レスポンスはレスポンス本文にプレーンテキストで記述されます。たとえば`method`パラメーターでコマンドを指定し忘れた場合、レスポンスは次のようになります。
一部のJSON-RPCリクエストは、HTTPレイヤーでエラーコードでレスポンスします。この場合、レスポンスはレスポンス本文にプレーンテキストで記述されます。たとえば`method`パラメータでコマンドを指定し忘れた場合、レスポンスは次のようになります。

```
HTTP Status: 400 Bad Request
Expand All @@ -105,14 +109,19 @@ HTTPステータスコード200 OKが返されるその他のエラーの場合

すべてのメソッドは、以下のいずれかの値の`error`コードを返す可能性があります。

* `unknownCmd` - リクエストに、`rippled`サーバが認識する[コマンド](../index.md)が含まれていません。
* `jsonInvalid` -（WebSocketのみ）リクエストは適切なJSONオブジェクトではありません。
* この場合JSON-RPCは、代わりに400 Bad Request HTTPエラーを返します。
* `missingCommand` -（WebSocketのみ）リクエストに`command`フィールドが指定されていませんでした。
* この場合JSON-RPCは、代わりに400 Bad Request HTTPエラーを返します。
* `tooBusy` - サーバの負荷が高すぎるため、現在このコマンドを実行できません。管理者として接続している場合は、通常このエラーが返されることはありません。
* `noNetwork` - サーバとXRP Ledgerピアツーピアネットワークのその他の部分との接続で問題が発生しています（サーバがスタンドアロンモードで実行されていません）。
* `noCurrent` - 高い負荷、ネットワークの問題、バリデータ障害、誤った構成、またはその他の問題が原因で、サーバが現行のレジャーを認識できません。
* `noClosed` - サーバに決済済みレジャーがありません。通常、このエラーは起動が完了していないことが原因で発生します。
* `wsTextRequired` -（WebSocketのみ）リクエストの[opcode](https://tools.ietf.org/html/rfc6455#section-5.2)がテキストではありません。
* `amendmentBlocked` - サーバの状態が[Amendment blocked](../../../concepts/networks-and-servers/amendments.md#amendment-blocked)であるため、XRP Ledgerネットワークとの同期を維持するために最新バージョンに更新する必要があります。
- `amendmentBlocked` - サーバの状態が[Amendmentブロック](../../../concepts/networks-and-servers/amendments.md#amendment-blocked)されたであるため、XRP Ledgerネットワークとの同期を維持するために最新バージョンに更新する必要があります。
- `failedToForward` - ([レポートモード][]のサーバのみ)サーバはこのリクエストをP2Pモードサーバに転送しようとしましたが、接続に失敗しました。
- `invalid_API_version` - サーバはリクエストの[APIバージョン番号](request-formatting.md#apiのバージョン管理)をサポートしていません。
- `jsonInvalid` -（WebSocketのみ）リクエストは適切なJSONオブジェクトではありません。
- この場合JSON-RPCは、代わりに400 Bad Request HTTPエラーを返します。
- `missingCommand` -（WebSocketのみ）リクエストに`command`フィールドが指定されていませんでした。
- この場合JSON-RPCは、代わりに400 Bad Request HTTPエラーを返します。
- `noClosed` - サーバに閉鎖済みレジャーがありません。通常、このエラーは起動が完了していないことが原因で発生します。
- `noCurrent` - 高い負荷、ネットワークの問題、バリデータ障害、誤った構成、またはその他の問題が原因で、サーバが現行のレジャーを認識できません。
- `noNetwork` - サーバとXRP Ledgerピアツーピアネットワークのその他の部分との接続で問題が発生しています（サーバがスタンドアロンモードで実行されていません）。
- `unknownCmd` - リクエストに、`rippled`サーバが認識する[コマンド](../index.md)が含まれていません。
- `tooBusy` - サーバの負荷が高すぎるため、現在このコマンドを実行できません。管理者として接続している場合は、通常このエラーが返されることはありません。
- `wsTextRequired` -（WebSocketのみ）リクエストの[opcode](https://tools.ietf.org/html/rfc6455#section-5.2)がテキストではありません。


{% raw-partial file="/docs/_snippets/common-links.md" /%}
158 changes: 111 additions & 47 deletions @i18n/ja/docs/references/http-websocket-apis/api-conventions/request-formatting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,71 +6,135 @@ seo:
---
# リクエストのフォーマット

## WebSocketフォーマット

`rippled`サーバへのWebSocketを開いた後、以下の属性を使用して、コマンドを[JSON](https://en.wikipedia.org/wiki/JSON)オブジェクトとして送信できます。

* コマンド名を最上位の`"command"`フィールドに指定します。
* このコマンドのすべての関連パラメーターも最上位に指定します。
* オプションで、任意の値を指定した`"id"`フィールドを指定します。このリクエストへのレスポンスでは、同一の`"id"`フィールドを使用します。そうすることで、レスポンスが順不同で到達した場合も、どのリクエストによってどのレスポンスを得られたのかがわかります。

レスポンスはJSONオブジェクトとして返されます。

## JSON-RPCフォーマット

JSON-RPCリクエストを実行するには、`rippled`サーバがJSON-RPC接続をリッスンしているポートおよびIPで、HTTP **POST**リクエストをルートパス（`/`）に送信します。HTTP/1.0またはHTTP/1.1を使用できます。HTTPSを使用する場合は、TLS v1.2を使用してください。セキュリティ上の理由から、`rippled`ではSSL v3以前を _サポートしていません_ 。

常に`Content-Type`ヘッダー（値`application/json`）を指定してください。

複数のリクエストを実行する予定の場合は、リクエスト間で接続を閉じてから開く操作を行わずに済むように、[Keep-Alives](http://tools.ietf.org/html/rfc7230#section-6.3)を使用してください。

以下の属性を指定したリクエスト本文を[JSON](https://en.wikipedia.org/wiki/JSON)オブジェクトとして送信します。

* コマンドを最上位の`"method"` フィールドに指定します。
* 最上位の`"params"`フィールドを指定します。このフィールドの内容は、コマンドのすべてのパラメーターが指定された1つの入れ子JSONオブジェクトのみを保持している**1要素配列**です。

レスポンスもJSONオブジェクトです。

## コマンドライン形式

コマンドラインでは、通常の（ダッシュが先頭に付いた）コマンドラインオプションの後にコマンドを指定し、その後に一連の限定的なパラメーターをスペースで区切って指定します。スペースやその他の特殊文字が含まれている可能性のあるパラメーター値は、一重引用符で囲みます。

### リクエストの例
## リクエストの例

{% tabs %}

{% tab label="WebSocket" %}
```
```json
{
"id": 2,
"command": "account_info",
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated"
"id": 2,
"command": "account_info",
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated",
"api_version": 1
}
```
{% /tab %}

{% tab label="JSON-RPC" %}
```
```json
POST http://s1.ripple.com:51234/
Content-Type: application/json

{
"method": "account_info",
"params": [
{
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated"
}
]
"method": "account_info",
"params": [
{
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"strict": true,
"ledger_index": "validated",
"api_version": 1
}
]
}
```
{% /tab %}

{% tab label="コマンドライン" %}
```
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true
```sh
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated strict
```
{% /tab %}

{% /tabs %}


## WebSocketフォーマット

`rippled`サーバへのWebSocketを開いた後、以下のフィールドを使用して、コマンドを[JSON](https://ja.wikipedia.org/wiki/JSON)オブジェクトとして送信できます。

| フィールド | 型 | 説明 |
|:--------------------|:----------|:-------------------------------------------|
| `command` | 文字列 | [APIメソッド](../public-api-methods/index.md)の名前。 |
| `id` | (多種) | _(省略可)_ リクエストを識別するための一意な値。このリクエストに対するレスポンスも同じ `id` フィールドを使用します。これにより、レスポンスが順番通りに返ってこない場合でも、どのリクエストがどのレスポンスを返したのかを知ることができます。 |
| `api_version` | 数値 | _(省略可)_ 使用するAPIのバージョン。省略時はバージョン1を使用します。詳細については、[APIのバージョン管理](#api-versioning)をご覧ください。 |
| (メソッドのパラメータ) | (多種) | トップレベルのメソッドに任意のパラメータを指定します。 |

サーバからのレスポンスについては[レスポンスのフォーマット](response-formatting.md)をご覧ください。

## JSON-RPCフォーマット

JSON-RPCリクエストを実行するには、`rippled`サーバがJSON-RPC接続をリッスンしているポートおよびIPで、HTTP **POST**リクエストをルートパス（`/`）に送信します。HTTP/1.0またはHTTP/1.1を使用できます。HTTPSを使用する場合は、TLS v1.2を使用してください。セキュリティ上の理由から、`rippled`ではSSL v3以前を _サポートしていません_ 。

`Content-Type`ヘッダ(値`application/json`)を常に指定してください。

複数のリクエストを実行する場合は、リクエスト間で再接続を行わずに済むように、[Keep-Alives](http://tools.ietf.org/html/rfc7230#section-6.3)を使用してください。

以下のフィールドを指定したリクエストボディを[JSON](https://en.wikipedia.org/wiki/JSON)オブジェクトとして送信します。


| フィールド | 型 | 説明 |
|:--------------------|:----------|:-------------------------------------------|
| `method` | 文字列 | [APIメソッド](../public-api-methods/index.md)の名前。 |
| `params` | 配列 | _(省略可)_ このメソッドのパラメータを持つネストされたJSONオブジェクトを含む**一要素の配列**。メソッドがパラメータを必要としない場合は、このフィールドを省略できます。 |

`params`配列内のオブジェクトには以下のフィールドを含めることができます。

| フィールド | 型 | 説明 |
|:--------------------|:----------|:-------------------------------------------|
| `api_version` | 数値 | _(省略可)_ 使用するAPIのバージョン。省略時はバージョン1を使用します。詳細については、[APIのバージョン管理](#api-versioning)をご覧ください。 |
| (Method Parameters) | (多種) | メソッドで利用する任意のパラメータ。 |

サーバからのレスポンスについては[レスポンスのフォーマット](response-formatting.md)をご覧ください。

## コマンドライン形式

APIのメソッド名は、通常の(ダッシュで始まる)コマンドラインオプションの後に、スペースで区切られた一部のパラメータを続けて指定します。スペースやその他の特殊文字を含む可能性のあるパラメータ値については、シングルクォートで囲んでください。すべてのメソッドがコマンドラインAPI構文を持っているわけではありません。詳しくは、[コマンドラインの使い方](../../../infrastructure/commandline-usage.md#client-mode-options)をご覧ください。

コマンドラインはJSON-RPCを呼び出すため、そのレスポンスは常にJSON-RPCの[レスポンスのフォーマット](response-formatting.md)と一致します。

コマンドラインは常に最新の[APIバージョン](#api-versioning)を使用します。

**注意:** コマンドラインインターフェイスは管理目的でのみ使用することを意図しており、_サポートされているAPIではありません_です。新しいバージョンの`rippled`では、警告なしにコマンドラインAPIに破壊的な変更が導入される可能性があります！


## APIのバージョン管理

`rippled`サーバは、使用するAPIバージョンを識別するために単一の整数を使用します。現在、`1`と`2`{% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}新規: rippled 2.0.0{% /badge %}の2つのAPIバージョンがあります。サーバは`version`APIメソッドでサポートされるAPIバージョンの範囲を報告します。<!-- TODO: add a link when `version` method is documented. -->

それぞれのAPIバージョンは、破壊的な変更が導入されるときに新しいAPIバージョン番号を導入します。プレリリースやベータ、開発バージョンでは、同じAPIバージョン番号で破壊的な変更を導入することがあり、`account_tx`リクエストを使用してAPIバージョン2を使用し、同じ接続でAPIバージョン1を使用して別の`account_tx`リクエストを行うことができます。

将来の`rippled`のバージョンで破壊的な変更が導入されると、新しいAPIバージョン3が導入されます。


### 破壊的変更

次の種類の変更は**破壊的変更**です。

- リクエストやレスポンスのフィールドの削除や名前の変更
- リクエストやレスポンスのフィールドの型の変更
- リクエストやレスポンスのフィールドの意味の変更
- リクエストやレスポンスのフィールドの位置の変更、または他のリクエストやレスポンスのフィールドの前への新しいフィールドの追加
- APIメソッドの削除や名前の変更
- 既存のクライアントから確認できるAPI関数の動作の変更
- 次の種類の変更は、gRPC APIにのみ適用されます。
- `proto`フィールド番号の変更
- 列挙型または列挙型値の削除または名前の変更
- `oneof`からのフィールドの追加または削除
- `oneof`の分割または統合
- メッセージフィールドが`optional`、`repeated`、または`required`であるかの変更
- リクエストまたはレスポンスのストリーム値の変更
- パッケージまたはサービスの削除または名前の変更

フルリリースで破壊的変更が加えられると、新しいAPIバージョン番号が導入されます。プレリリース版、ベータ版、開発版では、同じAPIバージョン番号に変更を加えることがあります。

### 非破壊的変更

次の種類の変更は**非破壊的変更**であり、APIバージョン番号の変更なしに発生する可能性があります。

- パラメータの位置の変更を含まない、新しいフィールドの追加
- 新しいAPIメソッドの追加

{% raw-partial file="/docs/_snippets/common-links.md" /%}
Loading

0 comments on commit c63237d

Please sign in to comment.