fteCreateBridgeAgent (建立並配置 MFT 通訊協定橋接器代理程式)

fteCreateBridgeAgent 指令會建立 Managed File Transfer 通訊協定橋接器代理程式及其相關聯的配置。為您要傳送檔案至其中及從中接收檔案的每一台檔案伺服器建立通訊協定橋接器代理程式。

重要事項:

在 IBM® MQ for AIX®, Linux®, and Windows上，只有身為 IBM MQ 管理者 (及 mqm 群組成員) 的使用者才能執行此指令。如果您嘗試以非 IBM MQ 管理者的使用者身分執行此指令，則會收到錯誤訊息BFGCL0502E: You are not authorized to perform the requested operation.，且指令將不會執行。

在 z/OS® 系統上，使用者必須滿足 (至少) 下列其中一個條件，才能執行指令:

是 mqm 群組的成員（如果 mqm 群組已定義在系統上）。
是 BFG_GROUP_NAME 環境變數所指名之群組的成員（如果已指名群組的話）。
指令執行時，BFG_GROUP_NAME 環境變數中未設定任何值。

用途

使用 fteCreateBridgeAgent 指令可建立通訊協定橋接器代理程式。如需如何使用通訊協定橋接器的概觀，請參閱通訊協定橋接器。此 fteCreateBridgeAgent 指令提供一些 MQSC 指令，必須針對代理程式佇列管理程式執行這些指令，才能建立下列代理程式佇列：

SYSTEM.FTE.AUTHADM1.agent_name
SYSTEM.FTE.AUTHAGT1.agent_name
SYSTEM.FTE.AUTHMON1.agent_name
SYSTEM.FTE.AUTHOPS1.agent_name
SYSTEM.FTE.AUTHSCH1.agent_name
SYSTEM.FTE.AUTHTRN1.agent_name
SYSTEM.FTE.COMMAND.agent_name
SYSTEM.FTE.DATA.agent_name
SYSTEM.FTE.EVENT.agent_name
SYSTEM.FTE.REPLY.agent_name
SYSTEM.FTE.STATE.agent_name
SYSTEM.FTE.HA.agent_name

這些佇列是內部系統佇列，您不得從中修改、刪除或讀取訊息，除非您刪除代理程式。下列位置的檔案中也提供了要執行的 MQSC 指令：MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc

如果您稍後想要刪除代理程式，此指令也提供了您必須執行的 MQSC 指令，以清除並刪除代理程式使用的佇列。 MQSC 指令位於下列位置的檔案中: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc。

fteCreateBridgeAgent 指令會在下列目錄中建立 ProtocolBridgeProperties.xml XML 檔案：MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name。

使用者必須自行手動建立 ProtocolBridgeCredentials.xml 檔案，因為 fteCreateBridgeAgent 指令不會再建立此檔案。

ProtocolBridgeCredentials.xml 檔案容許您定義使用者名稱及認證資訊，通訊協定橋接器代理程式使用這些資訊自行向通訊協定伺服器授權；ProtocolBridgeProperties.xml 檔案容許您定義多台通訊協定檔案伺服器，以便您可以傳送至多個端點。

MQ_INSTALLATION_PATH/mqft/samples/credentials/ 目錄中有一個範例 ProtocolBridgeCredentials.xml 。如需相關資訊，請參閱通訊協定橋接器認證檔案格式及通訊協定橋接器內容檔格式。

如果您執行 fteCreateBridgeAgent 指令並指定預設通訊協定檔案伺服器（-bt 參數），此預設伺服器會包含在 ProtocolBridgeProperties.xml 檔案中，且其主機名稱用於伺服器名稱。使用 -bt 參數時，您需要指定下列參數：

-bh
-btz
-bm
-bsl
-bfe
-bts

如果您沒有指定預設伺服器，則 ProtocolBridgeProperties.xml 檔案中沒有任何項目；您必須先手動新增至少一台伺服器，然後才能進行傳送。

Managed File Transfer 提供進階代理程式內容，可協助您配置通訊協定橋接器代理程式。與通訊協定橋接器相關的內容以 protocol 開頭。這些內容在進階代理程式內容: 通訊協定橋接器及進階代理程式內容: 通訊協定橋接器代理程式記載中有說明。如果您在通訊協定橋接器中看到非預期的行為，請檢閱這些 protocol 內容，並確保您已針對您的系統正確設定這些內容。

如果您看到 fteCreateBridgeAgent 指令的下列輸出：

BFGMQ1007I: The coordination queue manager cannot be contacted or has refused a connection attempt.
The WebSphere MQ reason code was 2058. The agent's presence will not be published.

它指出無法聯絡協調佇列管理程式，並針對原因提供 IBM MQ 原因碼。此參考訊息可能指示目前無法使用協調佇列管理程式，或您未正確定義配置。

重要事項：

在 AIX 及 Linux Managed File Transfer 指令上，使用 Socket 檔案與在相同主機上執行的代理程式處理程序進行通訊。

這些 Socket 檔案建立在代理程式的日誌目錄中，並在代理程式停止時刪除。在 IBM MQ Managed File Transfer 安裝中，此 Socket 檔案是以下列檔案路徑建立: <MQ_DATA_PATH>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME> ，其中 MQ_DATA_PATH 依預設為 /var/mqm 。

若為可重新配送的代理程式，會在下列目錄下建立此 Socket 檔案: <RE_DISTRIBUTABLE_DIRECTORY>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME>。

例如，如果代理程式名稱為 SRCAGENT，代理程式佇列管理程式名稱為 SRCAGENTQM，協調佇列管理程式名稱為 COORDQM，且可重新配送的代理程式從目錄 /home/myuser/mqmft-redist執行，則此 Socket 檔案的完整路徑為: /home/myuser/mqmft-redist/mqft/logs/COORDQM/agents/SRCAGENT/logs/SRCAGENT@SRCAGENTQM

其檔案路徑長度總計為 85 個字元。

Socket 檔案的這些作業系統所容許的路徑長度上限為 107 個字元。因此，在建立代理程式時，請小心確定 Socket 檔案路徑不超過 107 個字元。這對於可重新配送的代理程式尤其重要，代理程式的日誌目錄可以位於任意目錄位置。如需設定配置目錄的詳細資料，請參閱 fteCreateEnvironment 指令。

如果您啟動代理程式，或執行連接至代理程式的其他指令，且您的路徑長度超過 107 個字元，則會收到下列訊息:

BFGNV0159E: 嘗試連結至具有 FFDC 的 Socket 檔案失敗

特殊字元

如果使用的參數值包含特殊字元，請格外小心，以免指令 Shell 解譯字元的方式不符合預期。例如，包含空格、引號 (單或雙)、反斜線或正斜線字元等字元的完整檔案路徑及名稱，可能由指令 Shell 解譯，而不是直接傳遞至指令本身。若要避免指令 Shell 解譯字元，請以雙引號或單引號括住整個參數，或使用指令 Shell 的 ESC 序列來跳出特殊字元。在 Windows 上指定檔案路徑時，請確保將分隔字元反斜線 (\) 輸入為雙反斜線 (\\) ，即跳出反斜線 (\)。或者，您可以使用單一正斜線 (/) 字元作為分隔字元。"

Syntax

fteCreateBridgeAgent

參數

-agentName 代理程式名稱

必要項目。要建立的代理程式的名稱。代理程式名稱在其管理網域中必須是唯一的。

如需命名代理程式的相關資訊，請參閱物件命名慣例。

-agentQMgr 代理程式佇列管理程式名稱

必要項目。代理程式佇列管理程式的名稱。

-bt protocol_file_server_type

選用項目。指出您要定義預設通訊協定檔案伺服器。請指定下列其中一個選項：

FTP: 標準 FTP 伺服器
SFTP: SSH FTP 伺服器
FTPS: 使用 SSL 或 TLS 保護 FTP 伺服器

如果未指定此參數，將不會定義預設通訊協定伺服器。

-bh 伺服器主機名稱

僅當您也使用 -bt 參數指定預設通訊協定檔案伺服器時才需要。通訊協定檔案伺服器的 IP 主機名稱或 IP 位址。

-btz server_time_zone

僅當您也指定 -bt 參數時才需要（僅限於 FTP 和 FTPS 伺服器）。通訊協定檔案伺服器的時區。請按下列格式指定時區：Area/Location。例如：Europe/London。

您可以使用 -htz 參數來列出 -btz 的可能值。例如：fteCreateBridgeAgent -htz

-bm server_platform

僅當您也使用 -bt 參數指定預設通訊協定檔案伺服器時才需要。通訊協定檔案伺服器的平台類型。請指定下列其中一個選項：

UNIX®: 一般 UNIX 和 Linux 平台
WINDOWS: 通用 Windows 平台
OS400: IBM i 平台
附註: 如果橋接器代理程式要與執行 IBM i的 FTP 伺服器通訊，您必須同時將 bm 參數設為 OS400 及 blf 參數設為 OS400IFS 。

-bsl 伺服器語言環境

僅當您也指定 -bt 參數時才需要（僅限於 FTP 和 FTPS 伺服器）。通訊協定檔案伺服器的語言環境。請按下列格式指定語言環境：xx_XX。例如：en_GB。

xx 是 ISO 語言碼。如需有效值的清單，請參閱語言名稱表示法的代碼
XX 是 ISO 國碼。如需有效值的清單，請參閱國家/地區名稱及代碼元素

-bfe server_file_encoding

僅當您也使用 -bt 參數指定預設通訊協定檔案伺服器時才需要。通訊協定檔案伺服器上儲存的檔案的字元編碼格式。例如：UTF-8。

您可以使用 -hcs 參數來列出 -bfe 的可能值。例如：fteCreateBridgeAgent -hcs

-bts truststore_file

僅當您也指定 -bt 參數時才需要（僅限於 FTPS 伺服器）。指定用於驗證 FTPS 伺服器呈現的憑證的信任儲存庫路徑。

只有您也指定了 -bt 參數上的 FTPS 選項時，才能指定 -bts 參數。

-bp 伺服器埠

選用項目。通訊協定檔案伺服器所連接的 IP 埠。僅在您的通訊協定檔案伺服器未使用該通訊協定的預設埠時，才指定此參數。如果您沒有指定這個參數， Managed File Transfer 會使用檔案伺服器通訊協定類型的預設埠。

-blw

選用項目。將通訊協定檔案伺服器定義為具有有限的寫入能力。依預設，通訊協定橋接器代理程式需要通訊協定檔案伺服器允許刪除檔案、重新命名檔案，以及開啟檔案來附加寫入。指定此參數可以讓通訊協定檔案伺服器不允許這些檔案動作。檔案伺服器改為僅允許讀取及寫入檔案。如果您指定此參數，在傳送岔断時可能無法回復任何傳送，並可能會導致目前正在傳送的檔案失敗。

-blf server_listing_format

選用項目，僅限於 FTP 和 FTPS 伺服器。定義預設通訊協定檔案伺服器所傳回之列示檔案資訊的伺服器清單格式。選項如下：

UNIX

一般 UNIX 和 Linux 平台

WINDOWS

通用 Windows 平台

OS400IFS

IBM i 平台上的根檔案系統

附註：

如果橋接器代理程式要與執行 IBM i的 FTP 伺服器通訊，則必須將 bm 參數設為 OS400 ，並將 blf 參數設為 OS400IFS 。
您只能使用 Managed File Transfer 在根 (/) 檔案系統上傳送及接收檔案。其他檔案系統無法運作。

若要確認所應選取的格式，則可使用 FTP 用戶端程式執行目錄列示作業，從而選取最適用的格式。例如，

UNIX 會顯示下列類型的清單:


-rwxr-xr-x 2 userid groupId 4096 2009-07-23 09:36 filename

Windows 會顯示下列類型的清單:


437,909 filename

IBM i 會顯示下列類型的清單:

 OS400IFS  -rwxrwsrwx  3 USERID  0       8192 Mar  7 08:33 filename

預設值為大多數伺服器所採用的 UNIX。

-agentQMgr主機 agent_qmgr_host

選用項目。代理程式佇列管理程式的主機名稱或 IP 位址。

-agentQMgr埠 agent_qmgr_port

選用項目。用戶端連接代理程式佇列管理程式所使用的埠號。

-agentQMgr通道 agent_qmgr_channel

選用項目。用於連接至代理程式佇列管理程式的通道名稱。

-agentDesc 代理程式說明

選用項目。代理程式的說明，顯示在 IBM MQ Explorer中。

-ac 或 -authorityChecking

選用項目。此參數會啟用權限檢查。如果您指定此參數，代理程式會檢查是否已授權提交要求的使用者執行所要求的動作。如需相關資訊，請參閱限制 MFT 代理程式動作的使用者權限。

-s service_name

選用（僅限於 Windows）。指出代理程式以 Windows 服務方式執行。如果未指定 service_name，則此服務會命名為 mqmftAgentAGENTQMGR，其中 AGENT 是代理程式名稱，而 QMGR 是代理程式佇列管理程式名稱。

服務的顯示名稱 (顯示在「 Windows 服務」視窗的名稱直欄中) 一律為 Managed File Transfer Agent AGENT@QMGR。

-su 使用者名稱

選用（僅限於 Windows）。代理程式以 Windows 服務執行時，此參數會指定執行服務所使用的帳戶名稱。若要使用 Windows 網域使用者帳戶來執行代理程式，請以 DomainName\UserName格式指定值。若要使用本端內建網域中的帳戶執行服務，請以 UserName 格式指定值。

您使用 -su 參數指定的 Windows 使用者帳戶必須具有 Log on as a service 權限。如需如何授與此權限的相關資訊，請參閱以 Windows 服務方式執行 MFT 代理程式或日誌程式的指引。

指定 -s 時需要。

-sp 密碼

選用（僅限於 Windows）。 -su 參數所設定使用者帳戶的密碼。

此參數僅在指定 -s 時有效。如果在指定 -s 參數時不指定此參數，會產生一則警告訊息。此訊息警告您，您必須先使用「Windows 服務」工具設定密碼，然後服務才能順利啟動。

-sj 選項

選用（僅限於 Windows）。以 Windows 服務啟動代理程式時，以 -D 或 -X 的格式定義傳遞至 JVM 的選項清單。這些選項會使用 # 記號或分號 (;) 字元來區隔。如果您必須內含任何 # 或分號 (;) 字元，請將這些字元放在單引號內。

只有在指定 -s 時，此參數才有效。

-sl 選項

選用（僅限於 Windows）。設定 Windows 服務日誌層次。有效的選項是：error、info、warn、debug。預設值是 info。此選項在您發生 Windows 服務問題時會很有幫助。將它設為 debug，可以在服務日誌檔中提供更詳細資訊。

此參數僅在指定 -s 時有效。

-n

選用（僅限於 Windows）。指示代理程式以正常程序執行。此參數與 -s 選項互斥。如果既不指定 -s 參數，也不指定 -n 參數，則代理程式會配置為正常 Windows 處理程序。

-p configuration_options

選用項目。此參數會決定用於建立代理程式的配置選項集。依照慣例，會使用非預設協調佇列管理程式的名稱作為此參數的輸入。然後，fteCreateBridgeAgent 指令會使用與此非預設協調佇列管理程式相關聯的內容檔集。

只有在您想要使用不同於預設值的配置選項時，才需指定選用的 -p 參數。如果您沒有指定 -p，則會使用 installation.properties 檔案中定義的配置選項。如需相關資訊，請參閱配置選項。

-f

選用項目。強制指令改寫現有的配置。

-htz

選用項目。顯示您可以用作 -btz 參數的輸入的受支援時區清單。

-hcs

選用項目。顯示可用作 -bfe 參數的輸入的受支援字集清單。

執行 fteCreateBridgeAgent -hcs 指令，可列出 JVM 的已知字碼頁。這項資訊無法從外部來源取得，因為已知字碼頁會隨 JVM 而改變。

-mquserid user_id

選用項目。指定用來向指令佇列管理程式進行鑑別的使用者 ID。

-mqpassword password

選用項目。指定用來向協調佇列管理程式進行鑑別的密碼。

當指定 -mqpassword 參數時，您也必須指定 -mquserid 參數。如果您指定 -mquserid，但未指定 -mqpassword，則系統會提示您提供相關聯的密碼，不會顯示此密碼。

[MQ 9.3.0 Jun 2022] 從 IBM MQ 9.3 開始，指令預設為使用 MQCSP 鑑別，並將要鑑別的使用者 ID 和密碼傳送至 MQCSP 結構中的佇列管理程式。

-nolpw

選用項目。如果指令所連接的佇列管理程式不支援超過 12 個字元的密碼，請指定此參數。

當指定 -nolpw 參數時，您也必須指定 -mquserid 參數。如果您指定 -mquserid 及 -nolpw，但未指定 -mqpassword，則系統會提示您提供相關聯的密碼，不會顯示該密碼。

附註: 如果您指定 -nolpw 選項，且密碼長度超過 12 個字元，則指令會失敗，並顯示錯誤訊息 BFGCL0829E。

-credentialsFile 檔案路徑

選用項目。現有或新認證檔的完整檔案路徑， IBM MQ 鑑別詳細資料會新增至其中。

此指令支援將一組 IBM MQ 鑑別詳細資料新增至具名 Managed File Transfer 認證檔。當已啟用 IBM MQ 連線鑑別時，請使用這個指令。如果更新現有的詳細資料，則必須使用 -f 強制參數。

-userid username

選用項目。用來與認證詳細資料相關聯的使用者 ID。如果未指定使用者 ID，則認證詳細資料將套用至所有使用者。您還必須指定 -credentialsFile 參數。

-? 或 -h

選用項目。顯示指令語法。

-x

選用項目。建立代理程式配置以在高可用性模式下執行。

指定此參數會將新的選項 highlyAvailable 新增至 agent.properties 檔案。

範例

在此範例中，新的通訊協定橋接器代理程式 ACCOUNTS1 使用代理程式佇列管理程式 QM_ACCOUNTS 建立，並使用預設協調佇列管理程式。 ACCOUNTS1 連接至 FTP 伺服器 accountshost.ibm.com。此 FTP 伺服器在 Windows 上執行，使用歐洲/柏林的時區、de_DE 的語言環境以及 UTF-8 的檔案編碼。重新連接重試次數為 4：


fteCreateBridgeAgent -agentName ACCOUNTS1 -agentQMgr QM_ACCOUNTS -bt FTP
 -bh accountshost.ibm.com -bm WINDOWS -btz Europe/Berlin -bsl de_DE -bfe UTF8
 -agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1

在此範例中，新的通訊協定橋接器代理程式 ACCOUNTS2 使用代理程式佇列管理程式 QM_ACCOUNTS 建立，並使用預設協調管理程式。這時會建立沒有預設通訊協定檔案伺服器的 ACCOUNTS2。


fteCreateBridgeAgent -agentName ACCOUNTS2 -agentQMgr QM_ACCOUNTS

附註: 上述不適用於 Managed File Transfer Agent 可重新配送。

這裡的實務範例是 Managed File Transfer Agent 正在 Linux 或 Windows 方框上執行，但配置為與執行 IBM i的 FTP 伺服器進行通訊。如果您需要目的地檔案使用 IB 的原生字碼頁，則在提交傳送要求時必須使用 -dce 字碼頁參數。例如：


fteCreateTransfer -rt -1 -sa SRC -sm MFTQM -da OS400FTP -dm MFTQM -dce 37 -sce 1252 
-t text -de overwrite -df "<your-domain>:/home/mft/text/uploadwcp.log"
 "C:\temp\os400\Text\uploadwcp.log"

而且，如果您需要來自 IBM i的原生字碼頁中的接收檔案:


fteCreateTransfer -rt -1 -da SRC -dm MFTQM -sa OS400FTP -sm MFTQM -sce 37 -dce 1252 
-t text -de overwrite -df "C:\temp\os400\Text\downloadwcp.log" 
"<your-domain>:/home/mft/text/uploadwcp.log"

其他自訂作業

如果已使用 -bt 參數（及其他必要參數），則 ProtocolBridgeProperties.xml 檔案中會存在預設伺服器名稱。

如果您要新增其他 ftp 伺服器，或變更認證檔的位置，請參閱使用 ProtocolBridgeProperties.xml 檔案定義通訊協定檔案伺服器的內容。

回覆碼

0: 指令已順利完成。
1: 指令未順利結束。

使用 fteStartAgent 指令可啟動通訊協定橋接器代理程式。如需相關資訊，請參閱 fteStartAgent (啟動 MFT 代理程式)。 [z/OS] 另請參閱在 z/OS。