> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ArcScript 入門

> アイテム、フィード、オペレーション、キーワード、組み込みスクリプティングアイテムなど、ArcScript 言語のコアとなるコンセプトをサンプルスクリプトとともに解説します。

export const siteNameShort = "Arc";

export const siteName = "CData Arc";

{siteNameShort}Script は、{siteName} に含まれるXML ベースの言語で、カスタム処理ロジックを記述するために使用できます。{siteNameShort}Script を使用すると、ファイルやメッセージを簡単に変換し、他のビジネスプロセスと統合することができます。{siteNameShort} には、E メールの送信、バッチファイルの実行、ファイルの操作などのための完全な[サンプルスクリプト](#サンプルスクリプト)が含まれています。これらのサンプルを、管理コンソールからお客様のスクリプトおよびイベントに挿入することができます。

{siteNameShort}Script は、データアクセスおよびプロセッシングのあらゆる側面の管理を可能にするハイレベルなプログラミング言語です。[キーワード](./keyword-reference/keywords)、アトリビュート、アイテム、[オペレーション](./operations/operations)、およびフィードを使用してスクリプトを記述し、すべてのコネクタの[イベント](./scripting#イベントスクリプティング)、専用の[Script](../connectors/script) と[REST](../connectors/rest) コネクタ、および[XML Map コネクタ](../connectors/xml-map/xml-map)の[カスタムスクリプト](../connectors/xml-map/xml-map-advanced#custom-scripts)オプションで使用できます。

* **アトリビュート**：name-value ペアのname 部分で、attribute="address", value="123 Pleasant Lane" のように使われます。
  * アトリビュートを配列で表すには`#` 文字を使用します。つまり、配列は複数の値を含むことができ、各値は1をベースとしたインデックスを使って参照できます。
  * 例えば、`[myitem.myattribute#2]` は`myattribute` 属性の2番目の値を参照します。

* **アイテム**：Attribute-value ペアの関連するグループで、インプットとアウトプットを説明します。次に例を示します。

  ```
  Attribute="name" value="Bob"
  Attribute="address" value="123 Pleasant Lane"
  Attribute="phone" value="123-4567"
  ```

* **フィード**：住所や電話番号を含む顧客リストなどのアイテムのリスト。

* **オペレーション**：アイテムをインプットとして受け、フィードをアウトプットとして生成するメソッドの一般名。

* **キーワード**：[arc:set](./keyword-reference/op-arc-set) などの{siteNameShort}Script ステートメント。

<Note>{siteNameShort}Script の配列は、32768 メンバーに制限されています。</Note>

{siteNameShort}Script は多様なキーワードを持ち、次のようなことが可能です：

* スクリプトのインプットとアウトプットを説明する
* 実行フローを管理するためにIF/ELSE 構文やCASE 構文などのハイレベルなプログラミング構成を使う
* オペレーションを呼び出し、カスタムオペレーションを定義する
* オペレーションのインプットとして使用されるアイテム、およびフィード（オペレーションのアウトプット）を作成し変更する
* オペレーション呼び出しの結果得られるフィードを、アイテムの反復により処理する

## サンプルスクリプト

{siteNameShort} には、E メール送信などの一般的なアクションを自動化するための完全なコードスニペットが含まれています。[Script コネクタの設定タブ](../connectors/script#settings-tab)またはコネクタの**イベント**タブで、**スニペットを挿入**をクリックして、実行するアクションを選択します。必要なコードがカーソル位置に挿入されます。

次のセクションでは、これらのコードスニペットを使用および拡張してカスタム処理ロジックを記述する方法について説明します。

### イベントインプットの使用

各イベントには、操作のインプットパラメータとして使用できる関連インプットがあります。インプットパラメータは、info セクションのインプット属性によって定義されています。

イベントの定義済みインプットを使用して、送受信されたファイルを処理するか、エラーメッセージを含むE メールを送信します。その他のインプットも利用可能です。例えば、**After Receive** イベントで利用可能なインプットは以下のとおりです：

```xml theme={null}
<arc:info title="After Receive" desc="This event is fired after receiving a file.">
  <input name="WorkspaceId"      desc="The id of the workspace that is receiving file." />
  <input name="ConnectorId"      desc="The id of the connector that is receiving file." />
  <input name="Direction"        desc="The direction of transaction." />
  <input name="Filename"         desc="The name of the file that was received." />
  <input name="FilePath"         desc="The path of the file that was received." />
  <input name="Attachment#"      desc="The path of the attachment was received." />
  <input name="MessageId"        desc="The Id of the transaction." />
  <input name="ErrorMessage"     desc="If an error occurred, this will contain the error message." />
</arc:info>
```

### オペレーションの使用

付属のコードサンプルを使用して、組み込み[オペレーション](./operations/operations)の一部を呼び出します。次の例では、[appSendEmail](./operations/op-app-send-email) オペレーションを使用して、ファイルを受信した後にE メールを送信します。これを使用するには、単にプレースホルダーの値を置き替えます：

```xml theme={null}
<!-- Send Email -->
<arc:set attr="email.To"         value="Recipient(s)"/>
<arc:set attr="email.Subject"    value="Before Send"/>
<arc:set attr="email.Message"    value="File [Filename] was processed."/>
<arc:call op="appSendEmail"/>
```

<Note>上記のスクリプトは、**設定**（歯車アイコンをクリックしてアクセスします）で事前にメールサーバーを設定している場合にのみ機能します。[アラートタブ](../getting-started/administration/settings/alerts)の**E メールの設定**セクションに移動します。appSendEmail オペレーションは、同じメールサーバーを使用します。</Note>

### サンプルスクリプトの拡張

付属のコードサンプルを使用して、定義済みのインプットを[オペレーション](./operations/operations)に渡します。オペレーションに固有のインプットを渡すこともできます。例えば、[appSendEmail](./operations/op-app-send-email) オペレーションは、本文や添付ファイルなど、いくつかの追加インプットを受け付けます。[arc:set](./keyword-reference/op-arc-set) キーワードを使用して、これらの値を指定します。

[arc:call](./keyword-reference/op-arc-call) キーワードを使用して、イベント内の任意の組み込みオペレーションを呼び出したり、API を呼び出したりします。

ほかのキーワードを使用して、実行フローなどを制御します。{siteNameShort}Script は計算的に完全です。また、処理と自動化を容易にするための機能強化も含まれています。{siteNameShort}Script の構文とその機能について詳しくは、[スクリプティング](./scripting)を参照してください。

## {siteNameShort}Script のアイテム

フィードは、*アイテム*により成り立ちますが、{siteNameShort}Script ではアイテムはフィードの部品という以上の働きをします。アイテムは、オペレーションにインプットを提供するために使われることもあります。

### アイテムの宣言

読みやすさと、後でスクリプトを簡単に変更できるようにするため、CData は、{siteNameShort}Script で明示的なインプットアイテムを作成してそれらを別々の行でオペレーションに渡すことを推奨します。アイテムは、[arc:set](./keyword-reference/op-arc-set) キーワードを通じて作成され、名付けられ、アトリビュート値を与えられます：

```xml theme={null}
<arc:set item="input" attr="mask" value="*.txt" />
```

上のスニペットは、`input` という名前のアイテムの、`mask` アトリビュートに`*.txt` という値をセットします。この場合、インプットアイテムは{siteNameShort}Script の変数の働きをします。

ただし、`input` という名前のアイテムは宣言されていません。その代わりに、初回にアトリビュートをセットしようとすると、そのアイテムが生成されます。この例では、インプットアイテムが存在しない場合、アイテムが生成され、それにmask アトリビュートがセットされます。

<Tip>
  また、「省略記法」を使用してアイテムやアトリビュートを宣言することもできます。次に例を示します。

  ```xml theme={null}
  <arc:set attr="colors.myfavorite" value="green" />
  ```

  このスニペットは`green` という値を持つ`myfavorite` アトリビュートを持つ`colors` アイテムを作成します。
</Tip>

### クエリ文字列パラメータとしてのアイテムの受け渡し

明示的なインプットアイテムを作成する代わりに、[arc:call](./keyword-reference/op-arc-call) クエリ文字列パラメータの形でオペレーションにインプットパラメータを渡す方法もあります。アイテムを明示的に宣言する場合と、パラメータとして渡す場合の違いの例として、`file` というアイテムを宣言し、このアイテムを行を読み取るオペレーションに渡す次の行について考えてみましょう：

```xml theme={null}
<arc:set attr="file.file" value="[filepath]" />

<arc:call op="fileReadLine" in="file">
```

クエリ文字列パラメータを使用してこれを実現するには、代わりに次の構文を使用できます：

```xml theme={null}
<arc:call op="fileReadLine?file=[filePath | urlencode]">
```

<Note>この形式を使用するには、`urlencode` 引数を使用してパラメータをURL エンコードする必要があります。これにより、アプリケーションはエラーを発生させることなく、ファイル名の特殊文字や予約文字を正しく解析できるようになります。</Note>

### アトリビュート値の選択

アトリビュートを参照するには、構文`item.attribute`（例えば、`input.mask`）を使用します。あるアトリビュート値をクエリするには、括弧（\[ ]）でアトリビュート名を囲います。これは、文字列リテラルとしてではなく、文字列を評価したいということを示します。

例えば、次のコードスニペットを見てください：

```xml theme={null}
<arc:set item="item1" attr="attr1" value="value1"/>
<arc:set item="item1" attr="attr2" value="item1.attr1"/>
<arc:set item="item1" attr="attr3" value="[item1.attr1]"/>
```

結果は次のとおりです：

* `item1.attr1` は、`value1` のリテラル文字列の値を割り振られます。
* `item1.attr2` は、`item1.attr1` のリテラル文字列の値を割り振られます。
* `item1.attr3` は、`value1` の値を割り振られます。これは、文字列`[item1.attr1]` が`item1` の`attr1` アトリビュートとして実行時に評価されるからです。

<Note>文字列リテラルにおいて、バックスラッシュを使って、括弧からエスケープすることができます。</Note>

### デフォルトアイテム

{siteNameShort}Script では、*デフォルトアイテム*という、アイテムの内部スタックの中に黙示的で名付けられていないアイテムが常に存在します。このアイテムを使用して完全なスクリプトを書くこともできますが、ベストプラクティスは、必要に応じて独自の明示的なインプットおよびアウトプットアイテムを定義することです。これにより、スクリプトが読みやすくなり、既存のアトリビュートを上書きしてしまうリスクも減少します。単純なスクリプトの場合、次の2つのシナリオでデフォルトアイテムを使用すると、スクリプトを少し短く、書きやすくすることができます：

* オペレーションの呼び出し：デフォルトアイテムは、ほかのアイテムが指定されていない場合に、スクリプトによって呼び出されたオペレーションに渡されるアイテムです。これはつまり、[arc:set](./keyword-reference/op-arc-set) を使って、デフォルトの名付けられていないアイテムのアトリビュートを書いて、そのアトリビュートがスクリプト内の次に呼び出されるオペレーションのインプットとして渡されることを意味します。これは、オペレーションに必要なパラメータを提供する一つの方法です。
* オペレーションまたはスクリプトのアウトプット内の現在のアイテムを処理：オペレーションの結果の変数名を指定しなかった場合、オペレーションを起動する[arc:call](./keyword-reference/op-arc-call) ブロックの内部で、デフォルトアイテムはオペレーションで生成された現在のアイテムを参照します。

次のスニペットで示すように、{siteNameShort}Script のキーワードのアイテムアトリビュートを省略することでデフォルトアイテムを操作します：

```xml theme={null}
<arc:set attr="path" value="." />
```

## ビルトインアイテム

スクリプトで宣言されたアイテムに加えて、スクリプトのスコープでは、いくつかのビルトインアイテムが利用可能です。ビルトインアイテムは、HTTP リクエスト、レスポンスなどの一部にアクセスするインターフェースを提供します。これらのアイテムはHTTP リクエストのインプットをオペレーションのインプットにマッピングするために役立ちます。

以下のセクションで、ビルトインアイテムについて説明します。

### スクリプトインプット (\_input)

スクリプトへのインプットは`_input` アイテムから参照されます。`_input` アイテムには、スクリプトが実行された際にURL のクエリ文字列やPOST データで検出された変数が含まれます。もし、POST データに同じ名前の変数が存在する場合には、クエリ文字列の値をオーバーライドします。

スクリプト内でデフォルトアイテムから値を読み取るとき、`_input` から値を読み取っています。同様に、デフォルトアイテムに書き込んだアトリビュートは、スクリプトへのインプットとともにオペレーションのパラメータとして渡されます。情報ブロック、もしくはスクリプト内に定義された変数だけが`_input` アイテム内では有効です。

<Note>`_input` は、[arc:call](./keyword-reference/op-arc-call) ブロック内のデフォルトアイテムではありません。アクセスが必要な場合は、名前で参照する必要があります。</Note>

### スクリプトアウトプット (\_out\[n])

[arc:call](./keyword-reference/op-arc-call) キーワードにより生成されたフィード内の現在のアイテムには、デフォルトアイテムもしくはビルトイン`_outn` アイテムを通じてアクセスできます。`n` は[arc:call](./keyword-reference/op-arc-call) キーワードのネスティングのレベルです。例えば、単一の[arc:call](./keyword-reference/op-arc-call) キーワードの内部の場合、アイテム名は`_out1` です。[arc:call](./keyword-reference/op-arc-call) キーワードの3つのネストレベルの内部の場合は、`_out3` です。

### HTTP リクエスト (\_request)

URL クエリ文字列に渡された変数、スクリプトにPOST された変数、およびその他の変数に、`_request` アイテム内のアトリビュートのコレクションとしてアクセスできます。アトリビュートの指定されたコレクションにアクセスするには、読みたいアトリビュートの接頭辞としてコレクションの名前を使います。例えば、`[_request.qstring:name]` はクエリ文字列内の"name" 変数の値を読み、`[_request.form:name]` はフォームデータの"name" 変数の値を読みます。

| アトリビュート           | 説明                                                                            |
| ----------------- | ----------------------------------------------------------------------------- |
| `q[uery]string:*` | クエリ文字列パラメータの値にアクセスします。                                                        |
| `form:*`          | フォームデータ内の変数の値にアクセスします。                                                        |
| `server:*`        | サーバー変数の値にアクセスします。                                                             |
| `body`            | リクエストのraw コンテンツ（ボディ）にアクセスします。                                                 |
| `bodybase64`      | リクエストのbase64 エンコードされたコンテンツ（ボディ）にアクセスします。                                      |
| `auth:*`          | ユーザーの認証情報にアクセスします。`[_request.auth:isauthenticated]` でユーザーが認証されているかどうかを判定します。  |
| `other:*`         | リクエストに関するその他の情報にアクセスします。`[_request.other:applicationpath]` でアプリケーションパスを取得します。 |

### HTTP レスポンス (\_response)

`_response` アイテムは、スクリプトの書き手がHTTP レスポンスに対して直接書き込むことを許容します。次のアトリビュートを設定できます。

| アトリビュート             | 説明                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------- |
| `cookie:*`          | レスポンスにcookie をセットします。アトリビュート名は`cookie:` を接頭辞とするcookie 名で、アトリビュートの値がcookie の値となります。 |
| `writefile`         | 指定されたパスの内容をレスポンスに書き込みます。                                                           |
| `redirect`          | クライアントのブラウザにリダイレクトヘッダーを送ります。これはブラウザを別のURL にリダイレクトするために使用できます。                      |
| `statuscode`        | レスポンスのHTTP ステータスコードをセットします。                                                        |
| `statusdescription` | レスポンスのHTTP ステータス説明をセットします。                                                         |

### HTTP ヘッダー (\_httpheaders)

`_httpheaders` アイテムは、スクリプトおよびテンプレート内でHTTP ヘッダーに簡単にアクセスすることを可能にします。このアイテムを読むことで、HTTP リクエストヘッダーを読むことができます。このアイテムに書き込むことで、送信レスポンスヘッダーに書き込むことができます。例えば、次のような行でコンテンツタイプをセットできます：

```xml theme={null}
<arc:set item="_httpheaders" attr="content-type" value="application/xml"/>
```

### HTTP クッキー (\_cookies)

`_cookies` アイテムを使用して、リクエスト内でcookie を取得したり、レスポンス内でcookie をセットすることができます。複数のkey/value ペアを持つcookie は、cookie のkey/value ペアに対応するアトリビュートのコレクションとして表されます。cookie 名は、それぞれのコレクションのアトリビュートの接頭辞になります。

### ASP.NET セッション (\_session)

ASP.NET セッション変数は、{siteNameShort}Script では、`_session` アイテム経由で利用可能です。セッション内に保存されたオブジェクトは、このアイテムのアトリビュートとしてアクセスできます。アトリビュート名は、セッション内でオブジェクトを保存する際に使用されたキーとなります。

### {siteName} メッセージ (\_message)

ファイルが{siteNameShort} [フロー](../flows/flows)を通過するとき、アプリケーションはファイルにメタデータを追加します。オリジナルファイルとアプリケーションのメタデータの組み合わせは、*メッセージ*と呼ばれます。

`_message` アイテムは、スクリプティングコンテキスト（および[Email Send コネクタ](../connectors/email-send)の**Subject** フィールドのようなスクリプティングを解釈できるコネクタフィールド）でメッセージの本文とメタデータへのアクセスを提供します。

<Note>{siteNameShort}Script の配列は、32768 メンバーに制限されています。メッセージに32768 回以上繰り返されるヘッダーがある場合、最も古いヘッダーがメッセージから削除されます。</Note>

#### メタデータ

メッセージのメタデータには以下が含まれます：

* ファイル名の変更に関係なくファイルを識別する一意のId（*MessageId* と呼ばれます）
* 処理中の失敗と成功に関する情報
* フローでプログラムによって昇格されるカスタムメタデータ

メッセージのメタデータにアクセスするには、`_message` アイテムの`header:*` アトリビュートを使用します。例えば、{siteNameShort} 内のファイルの処理中にエラーが発生すると、そのファイルを表すメッセージに`x-trapped-errordescription` ヘッダーが追加されます。このヘッダーには、エラーが発生したConnectorId やエラーに関するデバッグ情報など、発生したエラーについての情報が格納されます。次の構文は、スクリプトコンテキスト内でこのヘッダーを参照します。

`[_message.header:x-trapped-errordescription]`

#### ボディ

メッセージの本文にアクセスするには、以下のように`_message` アイテムの`body` アトリビュートを使用します。

`[_message.body]`

これはメッセージの本文を文字列として返します。

#### 追跡されたヘッダーの追加

[追跡されたヘッダー](../getting-started/administration/activity#追跡されたヘッダー)をメッセージに追加するには、以下のように`_message` アイテムの`trackedheader` アトリビュートを使用します：

```xml theme={null}
<arc:set attr="output.filepath" value="[filepath]" />
<arc:set attr="_message.trackedheader:myHeaderName" value="Myvalue" />
<arc:push item="output" />
```

#### カスタムヘッダーの追加

ファイルにカスタムヘッダーを追加するには、コネクタによってプッシュされるファイルアイテムの`Header:header_name` アトリビュートを設定します。わかりやすくするために、入力ファイルの未変更バージョンを出力としてプッシュするスクリプトから始めます：

```xml theme={null}
<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:push item="outfile" />
```

`[FilePath]` 変数は入力ファイルのフルパス（およびファイル名）に解決されるため、このスクリプトは出力ファイルを入力ファイルと同じにします。

このスクリプトに次の追加を行うと、ファイルをプッシュする前にカスタムヘッダーがファイルに追加されます：

```xml theme={null}
<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.Header:myHeaderName" value="myValue" />
<arc:push item="outfile" />
```

**設定 > 高度な設定**ページの**高度な設定**セクションの**追跡されたヘッダー**フィールドに移動し、ヘッダー名を追加することで、ログでカスタムヘッダーを検索可能にすることができます。

#### コネクタイベントのログ

コネクタ定義イベントのログを{siteNameShort}Script の`_message` ボディに追加するには、`log` 属性プレフィックス、有効なログレベルエントリ、および`value` をメッセージに追加します。次の例は、属性の`value` 部分のテキストを含む`Info` 行をログファイルに追加します：

```xml theme={null}
<arc:set attr="_message.log:info" value="This is an info level log entry" />
```

有効なログレベルのエントリは以下のとおりです：

* Error
* Warning
* Info
* Debug
* Trace

### マッピングコンテキスト (\_map)

[XML Map コネクタ](../connectors/xml-map/xml-map)では`_map` アイテムが利用可能です。`_map` アイテムに設定されたアトリビュートは、マッピングの後半で常に使用可能です（言い換えれば、これらのアトリビュートがクリアされることはなく、`_map` アイテムがスコープ外になることはありません）。

`_map` アイテムは、マッピングの1つのポイントで計算され、マッピングの後半で参照される情報を格納するのに便利です。例えば、EDI ドキュメントを含むマッピングでは、ドキュメント内の*Line Items* の数をカウントし、このカウント値をドキュメントの最後にあるCTT セグメントに含める必要がある場合が考えられます。*Line Item* カウントを計算して`_map` アイテムのアトリビュートとして保存し、そのアトリビュートをCTT セグメントマッピングで参照することができます。

### アプリケーションログ (\_log)

`_log` アイテムは{siteNameShort} アプリケーションログへのフックです。このアイテムの`info` アトリビュートに文字列を設定すると、その文字列がアプリケーションログに表示されます。次に例を示します：

```xml theme={null}
<arc:set attr="_log.info" value="this string appears in the Application Log when the script executes" />
```

同一スクリプト内でこのアトリビュートを複数回設定することで、複数のメッセージをアプリケーションログに記録できます。アトリビュート値をクリアしたり追加したりする必要はありません。前の例で示したようにアトリビュート値を設定すると、指定された値がログに記録されます。

### {siteName} コネクタ (\_connector)

`_connector` アイテムは、現在のコネクタのフィールドおよびプロパティへのアクセスを提供します。利用可能なプロパティは、コネクタのフォルダにある*port.cfg* ファイルに格納されている値と同じであり、次の構文を使用してアクセスする必要があります。

`[_connector.propertyName]`

<Note>このアイテムを使用するには、コネクタにスクリプトコンテキストが必要です。これはコネクタの**イベント**タブで常に利用可能であり、一部のコネクタでは、設定可能な特別なフィールドで{siteNameShort}Script を評価することもできます。</Note>