> ## 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.

# Python の記述

> 組み込み変数、コンテキストオブジェクト、実用的な例を含む、CData Arc でPython スクリプトを記述および実行する方法。

export const siteNameShort = "Arc";

[前提条件](./python-prerequisites)を完了すると、{siteNameShort} は{siteNameShort}Script を記述できる場所であればどこでもPython を読み取って実行できます。これには、[Script](../connectors/script) コネクタ、[イベント](./scripting#イベントスクリプティング)、[XML Map](../connectors/xml-map/xml-map) コネクタのコードスクリプトなどが含まれます。

{siteNameShort} のスクリプティングエンジンに{siteNameShort}Script ではなくPython を使用するよう指示するには、使用する言語としてPython を定義する必要があります。これは、次に示すように[arc:script](./keyword-reference/op-arc-script) キーワードに`language` 属性を設定することで行います：

```xml theme={null}
<arc:script language="python">
# Python code goes here
</arc:script>
```

Python は{siteNameShort} のスクリプティングエンジンに直接埋め込まれているため、Python の記述に精通したユーザーは、スクリプト内でメッセージやコンテキストとやり取りする際に似たような構文を使用できます。

{siteNameShort}Script とPython を同じスクリプト内で使用することもできます。これは、すでに{siteNameShort}Script を記述しているが、Python を使用して追加のロジックを実装する必要がある場合に便利です。次の例に示すように、Python を使用して{siteNameShort}Script で記述された項目に直接アクセスできます：

```xml theme={null}
<arc:set attr="CustomerA.OrderID" value="123456" />
<arc:script language="python">
print("The OrderId for CustomerA is", _ctx.CustomerA.OrderID)
</arc:script>
```

{siteNameShort} では、多くのPython メソッドおよび変数がメッセージ、アイテム、アトリビュートのコンテキストと連携して動作します。

## 組み込みオブジェクトインターフェース

{siteNameShort} のPython 実装では、2つの主要なインターフェースが使用されます。これらは、以下に一覧表示する組み込み変数を保持し、それらへのアクセスを提供します：

* [{siteNameShort}ScriptContext](#scriptcontext)
* [{siteNameShort}ScriptItem](#scriptitem)

### {siteNameShort}ScriptContext

これは、{siteNameShort} のPython スクリプトのメインのスクリプティングコンテキストオブジェクトを表します。アイテムへのディクショナリのようなアクセスを提供し、ログ記録機能を含みます。このインターフェースは、コンテキストへのアクセスに使用できる`_ctx` 変数へのアクセスを提供します。

利用可能なメソッドは次のとおりです：

* [push](#push)
* [log](#log)

### {siteNameShort}ScriptItem

これは、{siteNameShort} のスクリプティング環境における個々のデータアイテムを表します。アトリビュートへのディクショナリのようなアクセスを提供し、値リストを保持します。次の変数は、自動的に利用可能な{siteNameShort}ScriptItem のインスタンスです：

* [\_input](#_input)
* [output](#output)
* [\_message](#_message)
* [result](#result)

利用可能なメソッドは次のとおりです：

* [get](#get)
* [clear](#clear)

大枠では、`_ctx` はスクリプティングコンテキストへのアクセスを提供し、`_input`、`output`、`_message` はあらかじめインスタンス化された{siteNameShort}ScriptItem オブジェクトです。カスタムアイテムを動的に作成またはアクセスするには、`_ctx.itemname` 構文を使用します。詳細については、[組み込み変数](#組み込み変数)および[オペレーション](#オペレーション)を参照してください。

## 組み込み変数

これらの変数は、スクリプティング環境におけるメッセージコンテキストの中核へのアクセスを提供します。これらを使用して、スクリプティングエンジンで利用可能なアイテムとやり取りします。

### \_ctx

スクリプティング環境にアクセスするためのメイン変数です。これは以下を提供します：

* スクリプトで利用可能なすべてのアイテムへのアクセス
* 新しいアイテムの作成、アイテムのプッシュ、およびアプリケーションログへのログ記録の機能

次の例では、`_ctx` 変数の`log` メソッドを呼び出して、`INFO` ログレベルを使用して[アプリケーションログ](../getting-started/administration/activity#アプリケーションログ)に情報を記録しています：

```xml theme={null}
<arc:script language="python">
...
_ctx.log('INFO', 'Successfully analyzed all data!')
...
</arc:script>
```

### \_input

スクリプティングエンジンの読み取り専用のインプットアイテムです。利用可能なアトリビュートは、スクリプトを記述するコンテキスト（コネクタの[アクションタイプ](../connectors/script#actions)など）によって異なります。例えば、*Transform* アクションに設定された[Script](../connectors/script) コネクタでは、次のアトリビュートを使用できます：

* ConnectorId
* WorkspaceId
* MessageId
* FilePath
* FileName
* Attachment#
* Header:\*

ただし、コネクタにインプットが提供されない*Trigger* アクションにScript コネクタを設定した場合、利用可能なのはConnectorId とWorkspaceId のみです。

次の例では、コネクタの名前を現在のメッセージのログファイルに出力します：

```xml theme={null}
<arc:script language="python">
...
print(_input.ConnectorId)
...
</arc:script>
```

次の例では、インプットファイルを取得して名前を変更し、元の名前をログに記録してから、新しい名前で同じファイルをプッシュします：

```xml theme={null}
<arc:script language="python">
originalname = _input.Filename
print("The original filename was ", originalname)
output.Filename = "mynewfile.xml"
output.Filepath = _input.Filepath
</arc:script>
```

次の例では、インプットファイルの名前をチェックして、それが生鮮品と非生鮮品のどちらのリストであるかを確認します。次に、ファイル名に基づいて生鮮品ヘッダーと値を設定します：

```xml theme={null}
<arc:script language="python">
# Check if it's a perishable product list based on the filename
is_perishable = "perishables" in _input.FileName.lower()
# Set a perishable header and value based on the filename
output['Header:category'] = 'perishable' if is_perishable else 'non-perishable'
</arc:script>
```

### output

単一のアウトプットのみが必要な場合に、独自のアイテムを作成してプッシュする代わりとなる組み込みアイテムです。`push()` を明示的に呼び出してアウトプットとして送信する必要があるカスタムアイテムとは異なり、`output` アイテムはスクリプトの完了時に自動的にプッシュされます。そのプロパティを変更するだけで、スクリプトの実行が完了すると、追加の`push()` 呼び出しを必要とせずにアウトプットとして自動的にプッシュされます。

アトリビュートをアイテムに直接設定することも、`dict` を使用して定義することもでき、独自に定義したアイテムに対しても同じことができます。次の例では、いくつかのデータを含むアウトプットファイルをプッシュします：

```xml theme={null}
<arc:script language="python">
output = {'data': 'This is a test',
          'filename': 'foo.txt'}
</arc:script>
```

次の例では、インプットファイルを取得して名前を変更し、元の名前をログに記録してから、新しい名前で同じファイルをプッシュします：

```xml theme={null}
<arc:script language="python">
originalname = _input.Filename
print("The original filename was ", originalname)
output.Filename = "mynewfile.xml"
output.Filepath = _input.Filepath
</arc:script>
```

### \_message

コンテキストにメッセージがロードされている場合に、現在のメッセージへのアクセスを提供します。この変数は、特定のシナリオでコネクタによってメッセージがアクティブに処理されている場合（コンテキストにメッセージがロードされている場合など）にのみアクセスできます。例えば、`_message` 変数は、[アクション](../connectors/script#actions)が*Trigger* に設定されたコネクタでは利用できません。これは、コネクタが処理を終えるまでメッセージが存在しないためです。この変数が利用できない場合、`_message is not defined` 例外が表示されます。

次のアトリビュートを使用できます：

* Header:Message-Id
* Header:FileName
* Header:\*
* body

次の例では、メッセージ本文に対していくつかの簡単な文字列操作を行います：

```xml theme={null}
<arc:script language="python">
# The message body in this example is plain text of "Example data for Arc."
# Perform string manipulation
transformed = _message.body.replace('a', '@').replace('e', '3')
print("Original:", _message.body)
print("Transformed:", transformed)
...
</arc:script>
```

結果として得られるアウトプットは、メッセージのログに出力されます：

```
Original: Example data for Arc.
Transformed: 3x@mpl3 d@t@ for Arc.
```

次の例は、`_message` アイテムからCustomerID ヘッダーを読み取り、現在のメッセージのログファイルにエントリとして出力する方法を示しています。

```xml theme={null}
<arc:script language="python">
...
print("The data is valid for customer", _message["Header:CustomerID"])
...
</arc:script>
```

### result

特に[XML Map](../connectors/xml-map/xml-map) スクリプトノードで使用する特別な変数です。これはスクリプト全体の結果として扱われます。この変数の値は、マップ内のノードの値として使用されます。ただし、[Script](../connectors/script) コネクタでのデバッグツールとしても使用できます。

次の例は、XML Map コネクタの宛先ノードのスクリプトで使用されるもので、先頭で宣言された{siteNameShort}Script アイテムからソースファイルのaddress/city xpath を読み取り、Python を使用して値を最初の3文字すべて大文字に変更します。新しい値は、`result` の値として送信されます：

```xml theme={null}
<arc:set attr="source.city" value="[xpath(address/city)]" />
<arc:script language="python">
city_value = _ctx.source.get("city")
# Normalize: extract from list if needed
if isinstance(city_value, list):
    city = city_value[0] if city_value else None
else:
    city = city_value
# Final logic
result = city[:3].upper() if city else ""
</arc:script>
```

次の例では、`result` 変数を使用してScript コネクタのログファイルにエントリを追加します：

```xml theme={null}
<arc:script language="python">
result = ["Step 1"]
output = {
  "Filename": "test.txt",
  "Data": "foo"
}
result.append("Step 2")
</arc:script>
```

スクリプトのアウトプットは次のようになります：

```
[2025-06-12T17:14:36.878-04:00][Info] Output File: test.txt
[2025-06-12T17:14:36.883-04:00][Info] Receiving done.
[2025-06-12T17:14:36.883-04:00][Info] Script output:
["Step 1","Step 2"]
```

## オペレーション

### log

`log(level, message)` は、`_ctx` 変数で利用可能なメソッドで、{siteNameShort} の[アプリケーションログ](../getting-started/administration/activity#アプリケーションログ)にエントリを直接書き込むことができます。利用可能なログレベルは、DEBUG、INFO、WARNING、ERROR です。

```xml theme={null}
<arc:script language="python">
...
_ctx.log('ERROR', f'Data evaluation failed in connector {_input.ConnectorId}!')
...
</arc:script>
```

前の例では、次のログエントリが生成されます：

<img src="https://mintcdn.com/cdata-arc/AKthyJ-LnqphL8js/public/images/python_log_result.png?fit=max&auto=format&n=AKthyJ-LnqphL8js&q=85&s=8c4530629ed8dc052d43c24c0cf845ad" alt="アクティビティログ内のPython ログ結果" width="700" data-path="public/images/python_log_result.png" />

### push

`push(item)` は、指定されたアイテムをスクリプトのアウトプットとしてプッシュします。アウトプットが指定されていない場合は、`output` アイテムがプッシュされます。

次の例では、新しいアイテム`foo` が{siteNameShort}ScriptContext に作成され、いくつかのデータとファイル名が割り当てられてからプッシュされます。

```xml theme={null}
<arc:script language="python">
foo = _ctx.foo
foo.Filename = "test2.txt"
foo.Data = "bar"
_ctx.push(foo)
</arc:script>
```

### get

`get(attr)` は、{siteNameShort}ScriptItem の指定されたアトリビュートの値を返します。このメソッドは、アトリビュートに名前でプログラム的にアクセスする方法を提供します。これは、ドット表記（`_input.myattr` など）を使用して直接アトリビュートにアクセスすること、またはディクショナリスタイルのアクセス（`_input.get('myattr')` など）と機能的に同等です。

次の例では、`item` オブジェクトの`tags` アトリビュートの値リストを、現在のスクリプトのログファイルに出力します。

```xml theme={null}
<arc:script language="python">
item = _ctx.item
item.name = 'Milk'
item.price = '2.99'
item.tags = ['perishable', 'dairy', 'noreturn']
print(item.get('tags'))
</arc:script>
```

### clear

`clear()` は、メソッドが呼び出された{siteNameShort}ScriptItem をクリアします。アイテムはそのまま残り、空になるだけです。

```xml theme={null}
<arc:script language="python">
product = _ctx.product
product.name = 'Milk'
product.price = '2.99'
product.tags = ['perishable', 'dairy', 'noreturn']
print("Before clear:", product)
# Use the clear() method to remove all items
product.clear()
print("After clear:", product)
</arc:script>
```

前の例では、次のアウトプットが生成されます：

* Before clear：`{"price":"2.99","name":"Milk","tags":["perishable","dairy","noreturn"]}`
* After clear：`{}`