Search

api:call

Version 23.0.8844

api:call

Version 23.0.8844

api:call キーワードは、オペレーションを呼び出すことに使われます。有効なオペレーションは次のとおりです：

  • アプリケーションのbin サブフォルダに位置する、アプリケーションアセンブリとともにインストールされているビルトインオペレーション
  • .NET、またはJava で独自に書き、アプリケーションのbin サブフォルダに置かれたオペレーション
  • 同じマシンに存在する他のスクリプトの呼び出し
  • HTTP でリモートマシンのスクリプトの呼び出し

オペレーションは、アイテムをインプットとして受け取り、フィードをアウトプットとして返します。api:call のスコープは、呼び出しから返されたフィード内のすべてのアイテムに対し実行されます。api:call のスコープ内では、返されたアイテムのアトリビュートを調べ、変更することができます。そして、それらのアトリビュートを他のオペレーションのインプットとして提供することができます。このようにオペレーションパイプラインが形成されます。もしくは、アイテムをアウトプットに追加することもできます。

アウトプットアイテムスタックとデフォルトアイテム

api:call が起こるたびに、内部のアイテムスタックに新しいアイテムが追加されます。スタックの一番上のアイテムがデフォルトアイテムです。アイテム名が呼び出しのインプットで明示的に指定されていない場合には、このアイテムがapi:call にインプットを提供します。

呼び出されたオペレーションはアトリビュートにデフォルトアイテムを書き込み、api:push がデフォルトアイテムをアウトプットに追加します。アイテムを追加する際に、スタックの一番上のデフォルトアイテムからのアトリビュートだけが追加されます。

デフォルトアイテムは、アイテムが反復されると消され、api:call は次のアイテムに働きます。つまり、次の反復では、api:call の前の反復のvalue セットを読むことはできません。反復に渡って値を残すには、api:set を使って、名前を明示したアイテムにコピーします。

デフォルトのアイテムは_ もしくは明示的に_out1、_out2、_out[n]、（N はスタック の深さです）と示すことができます。これにより、実行処理におけるすべての有効な値を読むことができます。ルックアップ処理はデフォルトアイテムからはじまり、値が見つかるまでスタック内を読みます。

下の例では、それぞれの呼び出しでアイテムがスタックの一番上に追加されること、およびデフォルトアイテムがそれぞれの呼び出しスコープ内で変化することを確認できます。

<api:call op="operation1"> 
ここでのデフォルトアイテムは_out1 です 
ここでプッシュすると、_out1 から属性がプッシュされます 
operation2 の呼び出しに使用されるインプットアイテムも_out1 です 
<api:call op="operation2"> 
ここでのデフォルトアイテムは_out2 です 
ここでプッシュすると、_out2 から属性がプッシュされます 
ここに別のapi:call があった場合、使用されるインプットアイテムは_out2 になります 
_out2 は、次の反復のためにここで一掃されます 
</api:call> 
ここでのデフォルトアイテムは再び_out1 です 
ここでプッシュすると、再び_out1 から属性がプッシュされます 
このレベルのインプットアイテムは再び_out1 です 
_out1 は、次の反復のためにここで一掃されます 
</api:call>

オペレーションにインプットを指定する

インプットを呼び出しに提供する3つの方法があります：

  • デフォルトアイテム：インプットアイテムが指定されない場合には、呼び出されたオペレーションはデフォルトアイテムのインプット値を読みます。呼び出された処理で使われるように、デフォルトアイテムの値の設定にはapi:set キーワードを使うことができます。 
    <api:set attr="mask" value="*.txt"/>
<api:set attr="path" value="C:\\"/>
<api:call op="fileListDir">
... 
</api:call>
  • 明示的なインプットアイテム：デフォルトアイテムを使う代わりに、オペレーションのインプットアイテムとして使いたいアイテムを明示的にパラメータ内で指定することができます。そうすると、デフォルトアイテムは使われず、次のように、指定されたインプットアイテムからインプット値が読まれ、オペレーションにクエリ文字列が渡されます。 
    <api:set attr="mask" value="*.* -- 無視されます--"/>
<api:set attr="myinput.mask" value="*.txt"/>
<api:set attr="myinput.path" value="C:\\"/>
<api:call op="fileListDir" in="myinput">
... 
</api:call>
  • クエリ文字列パラメータ：クエリ文字列表記を使って、オペレーションのインプットを特定することができます。クエリ文字列の一部として指定されたアトリビュートが優先されます。つまり、クエリ文字列で指定されたアトリビュートとインプットアイテムで指定されたアトリビュート名に差異がある場合、クエリ文字列のほうが優先されます。ただし、インプットアイテムの他のアトリビュートは、引き続きアクセス可能です。次の例では、クエリ文字列においてインプットを指定するシンタックスが説明されています： 
    <api:set attr="myinput.mask" value="*.txt -- オーバーライドされます --"/> 
<api:set attr="myinput.path" value="C:\\"/> 
<api:call op="fileListDir?mask=*.rsb" in="myinput">
...
</api:call>

パラメータ

  • op:呼び出されるオペレーションの名前。
  • in[put]:オペレーションを起こす際にインプットとして使われるアイテムのリスト。指定されたインプットアイテムの中でアトリビュートは左から右へルックアップされます。

  • out[put]:アウトプットアトリビュートが位置するアイテム。api:call のスコープで、指定されたアイテム名を使って、現在のアウトプットアイテムを取得することができます。_out[n]、または_pipe を使って、呼び出し結果を参照することができます。

    Note:呼び出しのスコープ外では、呼び出し内のアトリビュートセットは使用できません。これは、呼び出しのそれぞれの反復は、前の反復のアトリビュートを削除するためで、呼び出しの最後にはなにも残りません。呼び出しのスコープ外のアトリビュートにアクセスするためには、api:set を使って呼び出しの外で使いたいアイテムにアトリビュートを明示的にコピーします。

  • item:インプットとアウトプット双方で使われるアイテムの名前。
  • sep[arator]:マルチインプットアイテムを区切るためのセパレータ。デフォルトはカンマです。
  • ignoreprefix:見つけられたときに無視される接頭辞のカンマ区切りのリスト。いくつかのオペレーションでは、”prefix:name” （例えば、api:operation およびsql:company）のような名前のアトリビュートを返します。いくつかのシチュエーションでは、prefix:name および name を同じアトリビュートとして扱います。
  • page およびpagesize：反復されるアイテムのサブセット。オペレーション、もしくはフィード結果のページングを有効化するために使われます。例えば、page-“2”、およびpagesize=”5” を指定した場合に、api:call キーワードは結果フィードの6から10 のみを反復します。
  • httpmethod:処理が使うHTTP メソッド。
  • authtype:HTTP 経由でアクセスされたフィードにより要求される認証タイプ。例えば “basic” もしくは “digest”。
  • authtoken:HTTP 経由でアクセスされるフィードに認証するために使われるauth トークン。
  • user:HTTP 経由でアクセスされるフィードに認証するために使われるユーザー名。
  • password:HTTP 経由でアクセスされるフィードに認証するために使われるパスワード。
  • http_headers:HTTP 経由でアクセスされたフィードにより要求される他のHTTP ヘッダー。
  • proxyhost:HTTP リクエストが送信されるプロキシのアドレス。
  • proxyport:HTTP プロキシが起動しているTCP ポート。
  • proxyuser:HTTP プロキシへの認証に使われるユーザー名。
  • proxypassword:HTTP プロキシへの認証に使われるパスワード。
  • proxyauthtype:プロキシから要求されるHTTP 認証タイプ。例えば “basic” もしくは “digest”。
  • proxyssltype:プロキシサーバーへの接続時に使用するSSL タイプ。’AUTO またはALWAYS, NEVER, TUNNEL’ が使用可能です。デフォルトはAUTO です。

アトリビュートの制御

  • _index:api:call によって現在反復されているアイテムのインデックス。
  • _op:呼び出されているオペレーションの名前。実行までオペレーション名が知られていない場合に役立ちます。
  • _separator:マルチインプットアイテムを区切るためのセパレータ。

例

デフォルトアイテムをインプットとしてオペレーションを呼び出します。

<api:set attr="path" value="C:\myfiles"/>
<api:call op="fileListDir">
  <api:push/>
</api:call>

リモートマシン上の別のスクリプトを呼び出します。上の例のように、スクリプトがネストされます。

<api:call op="http://someplace.com/customerList.rsb">
  <api:push/>
</api:call>

関連項目

  • api:first:反復の一番はじめだけに実行されるエレメントを書く。
  • api:catch:呼び出し内でエラーをキャッチする。
  • api:continue:次の反復に続く。