InterSystems IRIS での MFT API の使用法
MFT ビジネス・ホストがニーズを満たさない場合は、MFT API を使用できます。これにより、サポートされている各 MFT サービスの接続、リソース (ファイルとディレクトリ)、およびユーザを管理できます。この API は、%SYS.MFT.Connection パッケージと %MFT パッケージで構成されています。提供されるメソッドは、以下のアクティビティをカバーします。
%SYS.MFT.Connection パッケージには、MFT サービスへのネットワーク接続を管理するためのメソッドが含まれています。%MFT パッケージには、サービス固有の機能に加えて、ファイル管理とユーザ管理のためのメソッドとプロパティが含まれています。どちらのクラスも、サポートされている MFT サービス (Box、Dropbox、および Kiteworks) ごとにサブクラスを持っています。接続を作成および管理する際は、常に接続固有のクラスを使用してください。
メソッドの使用例を以下に示します。ここにリストされているすべての項目の詳細 (すべてのメソッドとプロパティの詳細なパラメータ指定および戻り値を含む) については、%SYS.MFT.Connection および %MFT のクラスのクラス・リファレンス・エントリを参照してください。
接続管理 API
このセクションでは、プログラムによって保存された接続を作成して (ワンタイム設定)、接続オブジェクトを取得し、接続を管理する方法について説明します。
保存された接続を作成するための設定手順
MFT サービスへの接続を作成するには、まず次のワンタイム設定手順を実行します。
-
接続オブジェクトを作成します。これを行うには、使用するMFTサービスに応じて、%SYS.MFT.Connection.BoxOpens in a new tab、%SYS.MFT.Connection.DropboxOpens in a new tab、または %SYS.MFT.Connection.KiteworksOpens in a new tab の %New() メソッドを呼び出します。例 ：
set connection = ##class(%SYS.MFT.Connection.Dropbox).%New()
-
このオブジェクトの以下のプロパティを設定します。
-
Name — プロダクション内で使用するこの接続の名前。
-
Service — この接続に使用される MFT サービス。
-
SSLConfiguration — この接続に使用する TLS 構成の名前。
-
Username — MFT アカウントの管理者の電子メール・アドレス。
-
URL — 組織の転送サービス・ページのルート URL。
-
ApplicationName — MFT サービスで作成されたアプリの名前。
例 ：
set connection.URL = "https://companyname.kiteworks.com/"
-
接続オブジェクトを保存するには、(%Save() ではなく) Save() メソッドを呼び出します。例 ：
set status = connection.Save()
-
OAuth 2.0 クライアント情報を追加します。これを行うには、引数として次のプロパティを持つ同じクラスの CreateClient() クラス・メソッドを呼び出します。
-
name — MFT サービスで構成されたように、プロダクション用のエントリの名前。
-
sslConfiguration — この MFT 接続に使用される TLS 構成。
-
clientId — MFT サービスの OAuth 2.0 クライアント ID。
-
clientSecret — MFT サービスの OAuth 2.0 クライアント秘密鍵。
すべてのオプション引数を含む完全なシグニチャについては、クラス・リファレンスを参照してください。
例 ：
set status = ##class(%SYS.MFT.Connection.Dropbox).CreateClient(
OAuth2AppName,
"tlsconfig",
clientId,
clientSecret)}
このメソッドは、OAuth 2.0 クライアント情報を追加し、オブジェクトを再度保存します。レコードを正常に保存しなかった場合には、エラー・ステータスを返します。
これらの手順は、“前提条件と構成” の章の “Managed File Transfer 接続の作成” および “MFT 接続の許可” で説明されている手順と同じです。
接続の管理
GetConnection() を使用して接続オブジェクトを取得したら、次のメソッドを使用して、MFT 接続に関する情報を管理および取得します。特に明記されていない限り、これらは接続オブジェクト内のインスタンス・メソッドです。
GetAuthorizationCodeURL()
method GetAuthorizationCodeURL(redirect As %String,
scope As %String,
ByRef properties As %String,
Output sc As %Status) as %String
MFT サービスから許可を得るために使用する URL を返します。引数は以下のとおりです。
-
redirect は、リダイレクト URL です。
-
scope は、OAuth 2.0 のスコープです。
-
properties は、プロパティの多次元配列です。
-
sc は (これは参照によって返されます)、システムが URL を正常に取得したかどうかを示すステータス・コードです。
IsAuthorized()
method IsAuthorized(Output errorMessage As %String) as %Boolean
接続の許可ステータスをチェックします。1 つの引数があります。
ディレクトリおよびファイル管理 API
このセクションでは、MFT サービスでディレクトリとファイルを管理するために使用できるメソッドを示します。これらのメソッドは、サービス固有のサブクラス %MFT.BoxOpens in a new tab、%MFT.DropboxOpens in a new tab、および %MFT.KiteworksOpens in a new tab にあります。接続管理メソッドとは異なり、親クラス %MFT.APIOpens in a new tab からディレクトリおよびファイル管理メソッドを呼び出すことをお勧めします。例えば、%MFT.DropBox.CreateFolder() の代わりに %MFT.API.CreateFolder() を使用します。InterSystems IRIS は、メソッドが親クラスから呼び出されるたびに、すべての呼び出しを適切なサービス固有のバージョンとして自動的に処理します。特定のサービスに対して呼び出しが存在しない場合、InterSystems IRIS はそのステップをスキップし、次のステップに進みます。
Important:
Dropbox のディレクトリとファイルを管理するには、Dropbox の完全なアクセス権限を持つ Dropbox ユーザ・アプリケーションに基づく接続を使用する必要があります。
フォルダ・アクセスの管理
MFT サービスでフォルダを作成、削除、および共有するには、次のメソッドを使用します。
CreateFolder()
classmethod CreateFolder(connection As %SYS.MFT.Connection.Base,
folderPath As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
フォルダを作成し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).CreateFolder(connection,"/NewDir",.itemInfo)
DeleteFolder()
classmethod DeleteFolder(connection As %SYS.MFT.Connection.Base,
path As %String
permanent as %Boolean = 0) as %Status
フォルダを削除し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
path は、フォルダのフル・パスです。代わりに、この引数を "id:id_from_iteminfo" という形式の文字列として指定できます。ここで、id_from_iteminfo は %MFT.ItemInfoOpens in a new tab オブジェクトの ID です。
-
permanent は、完全な削除かどうかを指定します。permanent が 0 の場合、MFT サービスはフォルダをゴミ箱フォルダに移動します。permanent が 1 の場合、MFT サービスはフォルダを完全に削除します。このメソッドは現在、DropBox の完全なフォルダ削除をサポートしていないことに注意してください。
使用例 ：
set status = ##class(%MFT.API).DeleteFolder(connection,"/DirToDelete")
ShareFolder()
classmethod ShareFolder(connection As %SYS.MFT.Connection.Base,
path As %String,
accessLevel As %String = "viewer",
users As %List) as %Status
指定されたフォルダを特定のユーザ (特定のアクセス・レベルを付与します) と共有し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
path は、フォルダのフル・パスです。
-
accessLevel は、付与するアクセス・レベルを指定します。デフォルトは表示専用アクセスです。さまざまなレベルのアクセスについては、MFT サービスのドキュメントを参照してください。
-
users は、ユーザ名の %ListOpens in a new tab です。
使用例 ：
set status = ##class(%MFT.API).ShareFolder(connection,"/SharedDir/","editor",ListOfUsers))
UnshareFolder()
classmethod UnshareFolder(connection As %SYS.MFT.Connection.Base,
path As %String,
user As %String) as %Status
フォルダにアクセスする権限を付与されたユーザから特定のユーザを削除し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).UnshareFolder(connection,"/FolderToUnshare","mwinters")
UnshareFolderAll()
classmethod UnshareFolderAll(connection As %SYS.MFT.Connection.Base,
path As %String) as %Status
フォルダをどのユーザとも共有しないようにし、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).UnshareFolderAll(connection,"/FolderToUnshare")
MountFolder()
classmethod MountFolder(connection As %SYS.MFT.Connection.Base,
folderName As %String) as %Status
Dropbox のみ ： フォルダをマウントし (フォルダを所有者が共有している場合)、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.DropBox).MountFolder(connection,"MyFolder")
UnmountFolder()
classmethod UnmountFolder(connection As %SYS.MFT.Connection.Base,
folderName As %String) as %Status
Dropbox のみ ： フォルダ folderName をアンマウントし、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.DropBox).UnmountFolder(connection,"FolderName")
SetCurrentFolder()
classmethod SetCurrentFolder(connection As %SYS.MFT.Connection.Base,
folderPath As %String) as %Status
指定されたフォルダをプロダクションの現在の作業フォルダとして設定し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).SetCurrentFolder(connection,"/a/b/c")
フォルダ情報の取得
connection で指定された MFT サービスのフォルダに関する情報を取得するには、次のメソッドとプロパティを使用します。
GetCurrentFolder()
classmethod GetCurrentFolder(connection As %SYS.MFT.Connection.Base,
Output folderPath As %String) as %Status
現在の作業フォルダのフル・パス名を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetCurrentFolder(connection,.path)
GetFolderInfo()
classmethod GetFolderInfo(connection As %SYS.MFT.Connection.Base,
path As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
指定されたフォルダを取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetFolderInfo(connection,"/dirname",.itemInfo)
GetFolderContents()
classmethod GetFolderContents(connection As %SYS.MFT.Connection.Base,
folderPath As %String,
recursive As %Boolean = 0,
Output folderContents As %MFT.FolderContents) as %Status
指定されたフォルダの内容を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
folderPath は、フォルダのフル・パスです。
-
recursive は、サブフォルダを再帰的に取得するかどうかを制御します。
-
folderContents は (これは出力として返されます)、フォルダの内容へのハンドルを提供する %MFT.FolderContentsOpens in a new tab のインスタンスです (GetFolderContents() が成功を返した場合)。
使用例 ：
set status = ##class(%MFT.API).GetFolderContents(connection,"",IsRecursive,.contents)
クラス %MFT.FolderContentsOpens in a new tab のインスタンスには、以下のプロパティがあります。
Recursive
%MFT.FolderContents.Contents が再帰的なリストであるかどうかを示すブーリアン値。
ファイルの管理
connection で指定された MFT サービスのファイルを管理するには、次のメソッドを使用します。
DeleteFile()
classmethod DeleteFile(connection As %SYS.MFT.Connection.Base,
path As %String) as %Status
ファイルを削除し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).DeleteFile(connection,"/dirname/filetodelete.txt")
UploadFile()
classmethod UploadFile(connection As %SYS.MFT.Connection.Base,
localFilePath As %String,
filePath As %String,
replace As %Boolean = 0,
Output itemInfo As %MFT.ItemInfo) as %Status
ファイルをアップロードし、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
localFilePath は、ローカル・システム上のファイルのフル・パス名です。
-
filePath は、転送サービス内のファイルのフル・ターゲット・パス名です。
-
replace は、同じ名前を持つ既存のファイルを置き換えるかどうかを指定します。
-
itemInfo は (これは出力として返されます)、新規にアップロードされたファイルへのハンドルを提供する %MFT.ItemInfoOpens in a new tab のインスタンスです (UploadFile() が成功を返した場合)。詳細は、“%MFT.ItemInfo の詳細” を参照してください。
使用例 ：
set status = ##class(%MFT.API).UploadFile(connection,localdir_"file.txt","/uploadDir/file.txt",,.itemInfo)
DownloadFile()
classmethod DownloadFile(connection As %SYS.MFT.Connection.Base,
filePath As %String,
localFilePath As %String) as %Status
ファイルをダウンロードし、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
filePath は、転送サービス内のファイルのフル・パス名です。
-
localFilePath は、ローカル・システム上のファイルのフル・ターゲット・パス名です。
使用例 ：
set status = ##class(%MFT.API).DownloadFile(connection,"/DownloadDir/file.txt",localdir_"file.txt")
UploadStream()
classmethod UploadStream(connection As %SYS.MFT.Connection.Base,
stream As %BinaryStream,
filePath As %String,
replace As %Boolean = 0,
Output itemInfo As %MFT.ItemInfo) as %Status
指定されたストリームの内容をアップロードして、転送サービス内にファイルを作成し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
stream は、内容がアップロードされるストリームです。
-
filePath は、転送サービス内のファイルのフル・ターゲット・パス名です。
-
replace は、同じ名前を持つ既存のファイルを置き換えるかどうかを指定します。
-
itemInfo は (これは出力として返されます)、新しいファイルへのハンドルを提供する %MFT.ItemInfoOpens in a new tab のインスタンスです (UploadStream() が成功を返した場合)。詳細は、“%MFT.ItemInfo の詳細” を参照してください。
使用例 ：
set status = ##class(%MFT.API).UploadStream(connection,stream,"/uploadDir/newfile.txt",0,.itemInfo)
DownloadStream()
classmethod DownloadStream(connection As %SYS.MFT.Connection.Base,
filePath As %String,
ByRef stream As %BinaryStream) as %Status
ファイルをダウンロードして、ストリーム・オブジェクトを作成し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
-
connection は、GetConnection() を介して取得された、MFT サービスの接続オブジェクトです。
-
filePath は、転送サービス内のファイルのフル・パス名です。
-
stream は (これは参照によって返されます)、ファイルの内容を含むストリーム・オブジェクトです (DownloadStream() が成功を返した場合)。
使用例 ：
set status = ##class(%MFT.API).DownloadStream(connection,"/DownloadDir/file.txt",.resultstream)
ファイル情報の取得
%MFT.ItemInfoOpens in a new tab クラスは、ファイルに関する情報の API を提供します。GetFolder()、UploadFile()、および UploadStream() メソッド (前のセクションにリストされています) はそれぞれ、このクラスのインスタンスを出力として返します。%MFT.APIOpens in a new tab、%MFT.BoxOpens in a new tab、%MFT.DropboxOpens in a new tab、または %MFT.KiteworksOpens in a new tab クラスの GetFileInfo() メソッドを呼び出すことによって、このクラスのインスタンスを取得することもできます。
GetFileInfo()
classmethod GetFileInfo(connection As %SYS.MFT.Connection.Base,
path As %String,
Output itemInfo As %MFT.ItemInfo) as %Status
指定されたファイルに関する情報を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetFileInfo(connection,"filename.txt",.itemInfo)
%MFT.ItemInfo の詳細
クラス %MFT.ItemInfoOpens in a new tab のインスタンスには、以下のメソッドとプロパティがあります。
%MFT.ItemInfo.GetPath() メソッド
method GetPath(trailingSlash As %Boolean = 1) as %String
文字列としてファイルのパスを返します。引数 trailingSlash は、パスの末尾にスラッシュを含めるかどうかを指定します。
Modified プロパティ
アイテムの作成時刻を %Timestamp として UTC で示します。
ModifiedBy プロパティ
アイテムを最後に変更したユーザの内部識別子 (UserId) が文字列として含まれます。戻り値で %MFT.API.GetUsername() を使用して外部ユーザ名を取得します。
Type プロパティ
アイテムがファイル (1) かフォルダ (2) かを示します。
ユーザ管理 API
このセクションでは、MFT サービスでユーザを管理するために使用できるメソッドを示します。これらのメソッドは、サービス固有のサブクラス %MFT.BoxOpens in a new tab、%MFT.DropboxOpens in a new tab、および %MFT.KiteworksOpens in a new tab にあります。接続管理メソッドとは異なり、親クラス %MFT.APIOpens in a new tab からユーザ管理メソッドを呼び出すことをお勧めします。例えば、%MFT.DropBox.CreateUser() の代わりに %MFT.API.CreateUser() を使用します。InterSystems IRIS は、メソッドが親クラスから呼び出されるたびに、すべての呼び出しを適切なサービス固有のバージョンとして自動的に処理します。特定のサービスに対して呼び出しが存在しない場合、InterSystems IRIS はそのステップをスキップし、次のステップに進みます。
Important:
Dropbox のユーザを管理するには、チーム・メンバ管理権限を持つ Dropbox ビジネス・アプリケーションに基づく接続を使用する必要があります。
ユーザの作成と削除
ユーザを作成および削除するには、以下のメソッドを使用します。
CreateUser()
classmethod CreateUser(connection As %SYS.MFT.Connection.Base, userInfo As %MFT.UserInfo) as %Status
ユーザを作成し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
DeleteUser()
classmethod DeleteUser(connection As %SYS.MFT.Connection.Base, username As %String) as %Status
ユーザ名が指定されている場合、そのユーザを削除し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
DeleteUserById()
classmethod DeleteUserById(connection As %SYS.MFT.Connection.Base, userid As %String) as %Status
ユーザ ID が指定されている場合、そのユーザを削除し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
ユーザ・オブジェクトの取得
connection で指定された MFT サービスのユーザ情報を取得するには、次のメソッドを使用します。
GetUser()
classmethod GetUser(connection As %SYS.MFT.Connection.Base,
username As %String,
Output userInfo As %MFT.UserInfo) as %Status
ユーザ名が指定されている場合、そのユーザに関する情報を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetUser(connection,"User ToGet",.user)
GetUsername()
classmethod GetUsername(connection As %SYS.MFT.Connection.Base,
internalId As %String,
Output username As %String) as %Status
ユーザ ID が指定されている場合、そのユーザ名を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetUsername(connection,itemInfo.UserID,.username)
GetUserById()
classmethod GetUserById(connection As %SYS.MFT.Connection.Base,
userid As %String,
Output userInfo As %MFT.UserInfo) as %Status
ユーザ ID が指定されている場合、そのユーザに関する情報を取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetUserById(connection,itemInfo.ModifiedBy,.user)
GetUserList()
classmethod GetUserList(connection As %SYS.MFT.Connection.Base, Output userList As %MFT.UserList) as %Status
アカウントのすべてのユーザのリストを取得し、この操作の成否を示す %StatusOpens in a new tab 値を返します。このメソッドには、以下の引数があります。
使用例 ：
set status = ##class(%MFT.API).GetUserList(connection,.userList)
