# URLからの指定方法

外部でリンクを作成する際に、URLにパラメータを指定することで、既存のパラメータの値を上書きすることができます

## 対象機能

以下の機能で、URLからパラメータを指定することができます。\
これらの機能では、パラメータを変更する度にURLが更新され、**URLを他のユーザーと共有することで、パラメータの値を共有することができます**。

* ノートブックの[バージョン](/data-exploration/notebook/version.md)
* [レポート](/sharing/report.md)
  * レポートタイプが`インタラクティブレポート`の状態で公開されている必要があります
  * `自動実行`の設定が有効になっている場合、これらのパラメータがマージされた後に自動的に実行されます
  * `パラメータのデフォルト値を使用`の設定が有効になっている場合でも、**URLで指定されたパラメータが優先されます**
    * パラメータ全体がデフォルト値にリセットされた後に、URLで指定されたパラメータの更新が反映されます

## パラメータの指定方法

パラメータはURLの `cdm.params` クエリパラメータと同期します。\
`cdm.params` クエリパラメータは以下のような形式になっています。

```typescript
// ページ遷移時にもパラメータを保持するために、ページID毎にパラメータが保持されます
type Params = {[pageId: string]: {[paramId: string]: string}};

// パラメータの各値は、JSON.stringifyで文字列化して指定します（詳細は後述）
// pageId や paramId は実際は 68783eb9c4b4b71483a1d617 のような文字列になります
const params: Params = {
  "page1": {
    "param1": JSON.stringify("value1"),
    "param2": JSON.stringify(123)
  },
  "page2": {
    "param3": JSON.stringify(true),
    "param4": JSON.stringify(["value1", "value2"])
  }
};

const query = `?cdm.params=${encodeURIComponent(JSON.stringify(params))}`;
```

## ショートカット形式での指定方法

`cdm.params` クエリパラメータを外部で直接生成するのが困難な場合、 `cdm.params.${paramId}` 形式のキーと値を指定することで、パラメータを追加指定することもできます。 `cdm.params` と `cdm.params.${paramId}` の両方が指定された場合、 `cdm.params.${paramId}` の値が優先され、両方の値がマージされた新しい `cdm.params` クエリパラメータが自動的に指定されます。

```typescript
const paramId = "param1";
// ショートカット形式の場合、パラメータの値は JSON.stringify の文字列化は不要です（詳細は後述）
const value = "string_value";  

const query = `?cdm.params.${paramId}=${encodeURIComponent(value)}`;

// ショートカット形式では空文字列を指定することで、パラメータを空の状態にすることができます
const queryEmpty = `?cdm.params.${paramId}=`;
```

## パラメータの値の指定方法

パラメータの値は、パラメータの種類に応じて以下のように指定します。\
ショートカット形式で指定する場合、`JSON.stringify` の文字列化は不要ですが、URLに指定する際の、`encodeURIComponent` エンコードは必要です。

| 種類                           | 指定方法                                             | ショートカット形式               |
| ---------------------------- | ------------------------------------------------ | ----------------------- |
| <p>テキスト入力,<br>テキスト選択</p>     | `JSON.stringify("string_value")`                 | `string_value`          |
| <p>テキスト複数入力,<br>テキスト複数選択</p> | `JSON.stringify(["item1", "item2"])`             | `item1,item2`           |
| <p>数値入力,<br>数値選択</p>         | `JSON.stringify(123)`                            | `123`                   |
| 日付入力                         | `JSON.stringify("2025-01-01")`                   | `2025-01-01`            |
| 日付範囲                         | `JSON.stringify(["2025-01-01", "2025-01-02"])`   | `2025-01-01,2025-01-02` |
| チェックボックス                     | `JSON.stringify(true)`または`JSON.stringify(false)` | `true`または`false`        |

### 指定方法の説明

* 配列型のパラメータは、ショートカット形式では `,` で区切って指定します。
* 日付入力や日付範囲では `YYYY-MM-DD` の形式で指定してください
* 無効なパラメータの値が指定された場合、エラー画面に切り替わります


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.codatum.jp/data-exploration/parameter-overview/set-parameters-via-url.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.