將 IBM Aspera API 用於各種 IBM Aspera 產品和 SDK 的範例程式碼:
提出了各種程式語言。
IBM Aspera API 文件(在底部每頁選擇 24 個項目)。
Aspera Transfer SDK 文件包含程式碼範例。
有關傳輸 SDK 的視頻
IBM Aspera Connect SDK github 網站包含使用 Aspera Connect SDK 的範例。
IBM Aspera 提供兩種類型的 API:
客戶端 API:
SDK 包含應用程式中用於傳輸檔案的程式庫
伺服器API:
REST API(符合 OpenAPI 規範)與 Aspera 應用程式(Faspex、AoC、Node API、COS 等)交互
根據用例,人們可能會使用其中一個或(通常)多個 API。
此儲存庫的結構如下:
web
:顯示 web SDKd 使用的範例: Aspera Connect SDK和Aspera HTTP Gateway SDK
app
:使用Aspera Transfer SDK和Aspera 應用程式 REST API 的各種語言範例
在每個語言資料夾中,您會發現:
README.md
:該語言的特定自述文件Makefile
:用於運行範例的 makefilesrc
:原始碼src/utils
:輔助類src/examples
:範例程式範例程式將使用 YAML 設定檔中的伺服器位址和憑證。設定檔建立完成後,可以直接執行範例程式。
類別 Unix 系統:Linux、macOS...提供了一個Makefile
來運作範例。
Windows :請參閱下方的快速入門 (Windows)。 make
可能不可用。使用Makefile
作為參考來手動執行指令。
請參閱運行範例程式。
第一次執行make
時:將自動下載 Transfer SDK。
若要下載 SDK,請執行: make sdk
。
參考設定檔:將檔案config/config.tmpl
複製到private/config.yaml
並填入值。
md private
copy configconfig.tmpl privateconfig.yaml
將參數misc.platform
設定為windows-x86_64
在private/config.yaml
中編輯所需參數,例如 Faspex 連線資訊。
注意:是的,您還可以拖放、點擊、複製/貼上、使用記事本等編輯文件...
準備SDK資料夾
md tmp
下載 Aspera Transfer SDK(此處)並將其內容解壓縮到config/paths.yaml
中sdk_dir
標識的資料夾: <main folder>/tmp/transfer_sdk
注意:確保
config/paths.yaml
中標識的檔案如預期位於提取的資料夾中。例如,以下檔案必須存在:<main folder>/tmp/transfer_sdk/bin/asperatransferd
運行範例:請參閱運行範例程序
依照設定檔中的指定建立設定檔。並非所有值都是必需的,只需那些您想要運行的範例所需的值。
例如,若要執行單一範例,請使用make .tested/<sample name here>
:
$ cd app/python
$ make list
server aoc faspex faspex5 node shares node_v2
$ make .tested/faspex5
運行範例需要下載Transfer SDK守護asperatransferd
,以及一些編譯Transfer SDK proto檔案的工具,請參閱Transfer SDK。
詳細內容請參考各語言Makefile
中的配方。
提供了範本設定檔: config/config.tmpl
。
將檔案config/config.tmpl
複製到private/config.yaml
並填寫您自己的伺服器位址、憑證和參數。
cp config/config.tmpl private/config.yaml
vi private/config.yaml
注意:雖然格式可能類似於
ascli
的設定文件,ascli
的設定檔與此不相容。您必須建立一個新的。
將參數misc.platform
設定為所使用的架構:
osx-arm64
osx-x86_64
windows-x86_64
linux-x86_64
linux-s390
linux-arm64
linux-ppc64le
aix-ppc64
參數trsdk.url
可以設定為grpc://127.0.0.1:55002
(指定sdk將使用的本機連接埠)。
httpgw
部分僅由web
範例使用。
其他部分由各種範例使用。例如,如果您只想使用Transfer SDK測試COS傳輸,則可以只填寫cos
部分,其他部分留空。
範例(使用隨機憑證):
misc :
platform : osx-x86_64
level : debug
transfer_regular : true
trsdk :
url : grpc://127.0.0.1:55002
level : trace
ascp_level : trace
web :
port : 9080
httpgw :
url : https://1.2.3.4/aspera/http-gwy
server :
user : aspera
pass : demoaspera
url : ssh://demo.asperasoft.com:33001
file_download : /aspera-test-dir-small/10MB.1
folder_upload : /Upload
node :
url : https://node.example.com:9092
verify : false
user : node_user
pass : _the_password_here_
folder_upload : /Upload
faspex :
url : https://faspex.example.com/aspera/faspex
user : faspex_user
pass : _the_password_here_
cos :
endpoint : https://s3.eu-de.cloud-object-storage.appdomain.cloud
bucket : my_bucket
key : _the_key_here_
crn : ' crn:v1:bluemix:public:cloud-object-storage:global:_the_crn_:: '
auth : https://iam.cloud.ibm.com/identity/token
coscreds :
bucket : mybucket
service_credential_file : ./service_creds.json
region : eu-de
aoc :
org : acme
user_email : [email protected]
private_key : /path/to/my_aoc_key
client_id : aspera.global-cli-client
client_secret : frpmsRsG4mjZ0PlxCgdJlvONqBg4Vlpz_IX7gXmBMAfsgMLy2FO6CXLodKfKAuhqnCqSptLbe_wdmnm9JRuEPO-PpFqpq_Kb
workspace : Default
shared_inbox : TheSharedInbox
注意:帶有 HTTPS URL 的部分有一個參數
verify
。將其設為false
以停用開發環境的伺服器憑證驗證。
一些相對路徑在config/paths.yaml
中定義(保持這些值不變)。
可以設定以下日誌等級:
misc.level
:範例程式碼日誌等級: debug
info
warning
error
trsdk.level
:asperatransferd 日誌等級: trace
debug
info
warning
error
fatal
panic
trsdk.ascp_level
:ascp 日誌等級: trace
debug
info
一些範例支援在trsdk.url
中將連接埠設為0
(零)以使用隨機連接埠。
範例應用程式產生一個檔案asperatransferd.conf
提供給傳輸 sdk 守護進程,其中的日誌等級取自通用 yaml 設定檔。
Transfer SDK 是一項 gRPC 服務,可讓您在應用程式中傳輸檔案。它是一個可以用多種語言使用的客戶端 API。
檔案transfer.proto
描述了守護程式asperatransferd
提供的遠端過程呼叫介面。
+----------------+
+ transfer.proto +
+----------------+
|
[protoc]
|
v
+----------------------+ +------------+
+ generated stub code + + your code +
+----------------------+ +------------+
| [combine] |
+-----+----------------------+
|
v
+------------+ +---------------------+
| client app |-----[connect to]---->| Transfer SDK daemon |
+------------+ +---------------------+
| ^ | [executes]
+-------------[executes]----------------+ v
| +------+
[or other method, systemd, or manual]---[executes]------+ | ascp |
+------+
客戶端應用程式必須使用從transfer.proto
檔案產生的客戶端來源檔案。
為了方便起見,Transfer SDK 中提供了針對多種語言的生成(存根)程式碼。它可以直接使用,或者開發人員可以選擇從transfer.proto
檔案產生它們。為了生產和未來的兼容性,建議從transfer.proto
檔案產生存根程式碼。如果您自己產生存根程式碼,那麼您可以從最新平台和版本的支援中受益。
這裡的大多數範例都會從transfer.proto
檔案產生存根程式碼。
有關如何產生程式碼的說明,請參閱 GRPC 網站。
範例程式使用位於套件utils
中的幫助程式類別:
Configuration
從config.yaml
讀取組態參數,以便更輕鬆地執行任何範例。TransferClient
建立設定檔並啟動 Transfer SDK 守護程式: asperatransferd
Rest
用於 Rest API 上的簡單 API 呼叫。Transfer SDK 需要以下執行時間檔案:
asperatransferd
:提供 gRPC 服務的可執行文件ascp
:實際傳輸檔案的可執行檔ascp4
: ascp 的另一個版本async
:非同步操作的可執行文件libafwsfeed
:用於 Web 套接字的ascp
庫aspera-license
: ascp
的許可證文件(免費使用)可選文件:
aspera.conf
: ascp
的設定檔product-info.mf
:包含 SDK 版本資訊的 XML 文件aspera.conf
當在客戶端模式下使用時,該檔案對於ascp
是可選的。
最低限度的內容是:
< CONF />
可以設定一些客戶端參數,例如:
<? xml version = ' 1.0 ' encoding = ' UTF-8 ' ?>
< CONF version = " 2 " >
< default >
< file_system >
< storage_rc >< adaptive >true</ adaptive ></ storage_rc >
< resume_suffix >.aspera-ckpt</ resume_suffix >
< partial_file_suffix >.partial</ partial_file_suffix >
< replace_illegal_chars >_</ replace_illegal_chars >
</ file_system >
</ default >
</ CONF >
asperatransferd
是一個守護程式,必須在使用 Transfer SDK 之前啟動。它使用嵌入式ascp
驅動兩個端點之間的檔案傳輸。客戶端應用程式將使用指定連接埠上的 gRPC 連接到它。
SDK中沒有指定守護程式的啟動方式。開發人員可以選擇在單獨的終端機中手動啟動它,或者建立靜態設定檔並使用其他方法(例如 systemd 服務)啟動它。
此處提供的範例使用TransferClient
類別啟動守護程序。
當asperatransferd
啟動時,如果沒有透過選項--config
提供設定文件,則它期望在特定資料夾中找到ascp
、 ascp4
、 async
、 libafwsfeed
、 aspera-license
。為了將所有檔案放在同一個資料夾中,必須提供設定檔並設定資料夾。
範例中提供的 Makefile 下載 SDK 並將其解壓縮到單一資料夾中,然後範例相應地產生設定檔。
請參閱 HSTS 文件來建立使用者並取得憑證。
通常,節點 api 使用者是這樣創建的:
/opt/aspera/bin/asnodeadmin -a -u my_node_username -p my_node_password -x my_transfer_user
注意:存取金鑰憑證(id 和機密)也可用於節點 api 使用者。
Shares提供以下API:
<shares url>/node_api
。與Node API相同的範例可用於Shares 。
對於 Aspera on Cloud,需要幾個設定項:
org
:AoC 組織,即 URL 中.ibmaspera.com
之前的名稱user_email
:使用者的 IBMidprivate_key
:包含使用者私鑰的 PEM 檔案的路徑。使用者在其 AoC 使用者設定檔中配置了關聯的公鑰。client_id
:(見下文)客戶端應用程式標識符client_secret
:(見下文)客戶端應用程式秘密client_id
和client_secret
可以是:
aspera
CLI 之一:aspera.global-cli-client
frpmsRsG4mjZ0PlxCgdJlvONqBg4Vlpz_IX7gXmBMAfsgMLy2FO6CXLodKfKAuhqnCqSptLbe_wdmnm9JRuEPO-PpFqpq_Kb
例如,要擷取 Aspera Connect (Drive) 的內容: strings asperaconnect|grep -B1 '^aspera.drive$'
要測試向 COS 的傳輸,您將需要:
這是範例中的預設值。
或也可以使用:
private/service_creds.json
,然後:取得服務憑證