# GraphQL クエリの記述

## ポリシーコードをローカルでテストするために、入力値を用意したい

### `shishoctl testcase generate` コマンドを利用した、入力データの半自動生成

`shishoctl testcase generate` コマンドにより、入力データを規定する GraphQL クエリを、ポリシーコードへの入力として利用できる JSON ファイルを生成できます。

以下に `jobs[].decide.rego` ポリシーに対する入力として利用できる JSON 形式のテストデータを、GraphQL クエリから生成するコマンドの例を示します:

```sh
shishoctl testcase generate \
  --type decision \
  --org <YOUR_ORGANIZATION_ID> \
  --query-path (GraphQL クエリが格納されたファイルへのパス)
```

上記のように `shishoctl testcase generate` コマンドを利用する場合、`--type` 等のオプションを元に `shishoctl` コマンドが生成する JSON の形式を調整します。
GraphQL クエリのテスト用 Playground から返却されたデータをコピーアンドペーストするよりも、`shishoctl testcase generate` コマンドの利用が多くの場合では簡便でしょう。

### GraphQL クエリのテスト用 Playground を用いた、入力データの手動作成

Playground 上で GraphQL クエリをテスト実行した際に出力される JSON は、下記の例のように `data` 下に GraphQL クエリの実行結果を含む形式を取ります:

```json
{
  "data": {
    "github": {
      ...
    }
  }
}
```

上記データを適宜加工することによっても、ポリシーコードへの入力値を用意できます。

一方、[Rego インラインポリシーに対する API 定義](/docs/ja/g/api/rego.md) 等に記載があるように、利用しているポリシー言語や、ポリシーの利用箇所（例: `jobs[].decide` 以下か、あるいは `jobs[].notify` 以下か）によって「GraphQL クエリの実行結果がどのようにポリシーコードに与えられるか」は異なります。そこで、以下のセクションでは、いくつかのシチュエーションを例に、ポリシーに対する入力データを手動で作成する方法を紹介します。

#### 例: `jobs[].decide.rego` に指定する Rego ポリシーの場合

同フィールド上に指定された Rego インラインポリシーの場合、GraphQL クエリの実行結果は [`input`](/docs/ja/g/api/rego.md#input) 変数に格納されることになっています。
したがって、`opa eval -i input.json ...` 等のコマンドで `input` 変数に値を入力する場合、以下のような手順を踏む必要があります:

1. Playground から返却される JSON データの `data` フィールドの値**のみ** を JSON ファイルに保存する（例: `input.json`）
2. `opa eval -i input.json ...` 等のコマンドで、`input` 変数の値として、直上のステップで保存した JSON ファイルを指定してポリシーを評価する

以下に手順 1 で保存する JSON ファイルの例を示します:

```json
{
  "github": {
    ...
  }
}
```

#### 例: `jobs[].notify.rego`

同フィールド上に指定された Rego インラインポリシーの場合、GraphQL クエリの実行結果は [`input.query`](/docs/ja/g/api/rego.md#inputquery) 変数に格納されることになっています。
したがって、`opa eval -i input.json ...` 等のコマンドで `input` 変数に値を入力する場合、以下のような手順を踏む必要があります:

1. Playground から返却される JSON データの `data` フィールドのフィールド名を、`query` に置換して、JSON ファイルに保存する（例: `input.json`）
2. `opa eval -i input.json ...` 等のコマンドで、`input` 変数の値として、直上のステップで保存した JSON ファイルを指定してポリシーを評価する

以下に手順 1 で保存する JSON ファイルの例を示します:

```json
{
  "query": {
    "github": {
      ...
    }
  }
}
```

## GraphQL クエリのテスト用 Playground から返される値が、連携した外部サービス上の値と一致しない

Playground で返される値は、実際に Shisho Cloud 組織に連携された外部サービスから取得されたデータではなく、ランダムに生成されたテストデータです。
ランダムなデータではあるものの、可能な限り実際のポリシーに与えられるデータに近い形式を取るように設定されています。

:::info
もし不自然な値や、生成された値に関する不明点がある場合はサービス運営元（Flatt Security）にお問い合わせください。
:::