Version 24.2.9039

• サンプルスクリプト
  • イベントインプットの使用
  • オペレーションの使用
  • サンプルスクリプトの拡張
• ArcScript のアイテム
  • アイテムの宣言
  • クエリ文字列パラメータとしてのアイテムの受け渡し
  • アトリビュート値の選択
  • デフォルトアイテム
• ビルトインアイテム
  • スクリプトインプット (_input)
  • スクリプトアウトプット (_out[n])
  • HTTP リクエスト (_request)
  • HTTP レスポンス (_response)
  • HTTP ヘッダー (_httpheaders)
  • HTTP クッキー (_cookies)
  • ASP.NET セッション (_session)
  • CData Arc メッセージ (_message)
    • メタデータ
    • ボディ
  • 追跡されたヘッダーの追加
    • カスタムヘッダーの追加
    • コネクタイベントのログ
  • マッピングコンテキスト (_map)
  • アプリケーションログ (_log)
  • CData Arc コネクタ (_connector)

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

ArcScript は、データアクセスおよびプロセッシングのあらゆる側面の管理を可能にするハイレベルなプログラミング言語です。キーワード、アトリビュート、アイテム、オペレーション、およびフィードを使用してスクリプトを記述し、すべてのコネクタのイベント、専用のScript コネクタ、およびXML Map コネクタのカスタムスクリプト オプションで使用できます。

• アトリビュート：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 などのArcScript ステートメント。

ArcScript は多様なキーワードを持ち、次のようなことが可能です。

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

サンプルスクリプト

Arc には、E メール送信などの一般的なアクションを自動化するための完全なコードスニペットが含まれています。Script connector Settings tab またはコネクタのイベント タブで、スニペットを挿入 をクリックして、実行するアクションを選択します。必要なコードがカーソルに挿入されています。

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

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

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

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

<arc:info title="After Receive"  desc="このイベントはファイルを受信した後に発生します。">
  <input name="WorkspaceId"      desc="ファイルを受信しているワークスペースのId。" />
  <input name="ConnectorId"      desc="ファイルを受信しているコネクタのId。" />
  <input name="Direction"        desc="トランザクションの方向。" />
  <input name="Filename"         desc="受信されたファイルの名前。" />
  <input name="FilePath"         desc="受信されたファイルのパス。" />
  <input name="Attachment#"      desc="受信された添付ファイルのパス。" />
  <input name="MessageId"        desc="トランザクションのId。" />
  <input name="ErrorMessage"     desc="エラーが発生した場合は、エラーメッセージが表示されます。" />
</arc:info>

オペレーションの使用

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

<!-- E メールを送信 -->
<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：上記のスクリプトは、設定（歯車アイコンをクリックしてアクセスします）で事前にメールサーバーを設定している場合にのみ機能します。アラートタブのE メールの設定セクションに移動します。appSendEmail オペレーションは、同じメールサーバーを使用します。

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

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

arc:call キーワードを使用して、イベント内の任意の組み込み操作を呼び出したり、API を呼び出したりします。

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

ArcScript のアイテム

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

アイテムの宣言

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

<arc:set item="input" attr="mask" value="*.txt" />

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

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

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

<arc:set attr="colors.myfavorite" value="green" />

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

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

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

<arc:set attr="file.file" value="[filepath]" />

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

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

<arc:call op="fileReadLine?file=[filePath | urlencode]">

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

アトリビュート値の選択

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

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

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

デフォルトアイテム

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

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

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

<arc:set attr="path" value="." />

ビルトインアイテム

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

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

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

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

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

Note：_input は、arc:call ブロック内のデフォルトアイテムではありません。アクセスが必要な場合は、名前で参照する必要があります。

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

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

HTTP リクエスト (_request)

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

HTTP レスポンス (_response)

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

HTTP ヘッダー (_httpheaders)

_httpheaders アイテムは、スクリプトおよびテンプレート内でHTTP ヘッダーに簡単にアクセスすることを可能にします。アイテムを読むことで、HTTP リクエストヘッダーを読むことができます。アイテムに書き込むことで、outgoing レスポンスヘッダーに対して書き込むことができます。必要な情報は、以下のようにしてライン付きのコンテンツタイプをセットすることができます。

<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 セッション変数は、ArcScript では、_session アイテム経由で利用可能です。セッション内に保存されたオブジェクトは、このアイテムのアトリビュートとしてアクセスできます。アトリビュート名は、セッション内でオブジェクトを保存する際のキーとなります。

CData Arc メッセージ (_message)

ファイルがArc フローを通過するとき、アプリケーションはファイルにメタデータを追加します。オリジナルファイルとアプリケーションのメタデータの組み合わせは、メッセージと呼ばれます。

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

メタデータ

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

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

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

[_message.header:x-trapped-errordescription]

ボディ

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

[_message.body]

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

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

追跡されたヘッダーをメッセージに追加するには、以下のように _message アイテムの trackedheader アトリビュートを使用します。

<arc:set attr="output.filepath" value="[filepath]" />
<arc:set attr="_message.trackedheader:myHeaderName" value="Myvalue" />
<arc:push item="output" />

カスタムヘッダーの追加

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

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:push item="outfile" />

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

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

<arc:set attr="outfile.FilePath" value="[FilePath]" />
<arc:set attr="outfile.Header:myHeaderName" value="myValue" />
<arc:push item="outfile" />

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

コネクタイベントのログ

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

<arc:set attr="_message.log:info" value="This is an info level log entry" />

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

• Error
• Warning
• Info
• Debug
• Trace

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

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

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

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

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

<arc:set attr="_log.info" value="this string appears in the Application Log when the script executes" />

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

CData Arc コネクタ (_connector)

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

[_connector.propertyName]

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