攝取函數

Adp.Ingest 類別是用來將不同來源的資料載入表格和檢視。

Python 適用的 Autonomous Database Load Data API 允許下列作業：

將表格從「資料庫連結」複製到目前綱要的表格或視觀表
將物件從「雲端儲存連結」複製到目前綱要的表格或外部表格
使用 json 的資料建立表格

這些作業會建立對應的「攝取工作」

資料庫連結作業

「資料庫連結」函數提供「資料庫連結」之應用程式設計介面的類別、方法、屬性和參數的語法和描述。

取得用戶群組程序

此函數會接收用於執行 SQL 或 PL/SQL 程式碼的用戶群組清單。值與連線至資料庫時可用的資料庫服務相符。您必須具備 CS_SESSION 套裝程式的 EXECUTE 權限，才能使用此功能。

語法

Ingest.get_consumer_groups()

範例

在此範例中，您會取得用戶群組的清單：

adp.Ingest.get_consumer_groups() //Output:['LOW', 'MEDIUM', 'HIGH']

取得資料庫連結程序

傳回可用的資料庫連結清單 (若要建立資料庫連結，請參閱「Oracle® Database Database Administrator's Guide 21c」中的「資料庫連結」)。

Ingest.get_database_links(owner)

參數：

擁有者：此欄位顯示「資料庫連結」的擁有者。如果沒有這個欄位，工具會使用目前的綱要擁有者。

範例

在此範例中，您會取得「資料庫連結」的清單：

adp.Ingest.get_database_links()
 
//Output
{"nodes":
[
    {"label":"***********_*********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
     "type":"DB_LINK",
     "id":"\"ADPTEST\".\"DB_LINK\".\"***********_*********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM\"",
    "data":{
        "name":"********_*******_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
        "namespace":"DB_LINK",
        "path":"\"DB_LINK\".\"*************_********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM\"",
        "schema":"ADPTEST",
        "application":"DATABASE",
        "created":"2024-05-02T08:30:15Z",
        "updated":"2024-05-02T08:30:15Z"
        }
    }
],"links":[]}

取得資料庫連結程序中的表格

從資料庫連結傳回表格和視觀表清單。

Ingest.get_db_link_owner_tables(db_link)

參數：

db_link ：此資料庫連結的名稱。

範例

在此範例中，您會取得指定「資料庫連結」中的物件清單：

adp.Ingest.get_db_link_owner_tables("**************_********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM")
 
//Output
[
"APEX_DG_DATASET_ROWS": {
    "dbLink": "**************_********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "APEX_230200",
    "tableName": "APEX_DG_DATASET_ROWS",
    "numRows": 3,
    "avgRowLen": 54
  },...
]

從資料庫連結程序複製表格

從指定的表格建立目前資料庫的表格。

語法

Ingest.copy_tables_from_db_link(tables, consumer_group)

參數：

表格：表格描述的陣列。每個描述都有 4 個欄位。
擁有者：此欄位顯示「資料庫連結」的擁有者。如果沒有這個欄位，工具會使用目前的綱要擁有者。
table_name ：「資料庫連結」中的表格名稱。您必須在此欄位中輸入值。
db_link ：資料庫連結的名稱。您必須在此欄位中輸入值。
target_table_name ：目標表格的名稱。如果缺少此欄位，則工具會使用來源表格名稱。
consumer_group ：用戶群組。預設值為 "LOW"。

範例

在此範例中，您可以根據「資料庫連結」中的表格建立表格：

adp.Ingest.copy_tables_from_db_link([{'owner':'SH', 'tableName':'PRODUCTS', 'dbLink':'PHOENIX119757_ORDS_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM','targetTableName': 'PRODUCT'}], 'HIGH')
 
//Output
 
[
    {
    'schema': 'SH',
    'tableName': 'PRODUCTS',
    'targetTableName': 'PRODUCTS',
    'name': '***********_***********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM',
    'rowsCopied': 766
    }
]

此方法會傳回您所建立的表格清單。輸出的字典與輸入參數中的字典相同，另一個值為插入的資料列計數。

資料庫連結程序的連結表格

從指定的表格建立目前資料庫的視觀表。請考慮結果字串沒有資料列數目。

Ingest.link_tables_from_db_link(tables, consumer_group)

參數：

表格：表格描述的陣列。每個描述都有 4 個欄位
- 擁有者：此欄位顯示「資料庫連結」的擁有者。如果沒有這個欄位，工具會使用目前的綱要擁有者。
- table_name ：「資料庫連結」中的表格名稱。您必須在此欄位中輸入值。
- db_link ：資料庫連結的名稱。您必須在此欄位中輸入值。
- target_table_name ：目標表格的名稱。如果缺少此欄位，則工具會使用來源表格名稱。
consumer_group ：用戶群組。預設值為 "LOW"。

範例

在此範例中，您可以根據「資料庫連結」中的表格建立表格：

adp.Ingest.link_tables_from_db_link([{'owner':'SH', 'tableName':'PROMOTIONS', 'dbLink':'**************_********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM', 'targetTableName': 'PROMOTIONS'}},'HIGH')
 
//Output
 
[
    {
    'schema': 'SH',
    'tableName': 'PROMOTIONS',
    'targetTableName': 'PROMOTIONS',
    'name': '**************_********_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'}
]

雲端儲存體連結作業

「雲端儲存連結」功能提供 Data Studio 工具套件之「雲端儲存連結」工具應用程式設計介面的類別、方法、屬性以及參數的語法和描述。

這些方法可讓您管理「證明資料」和「雲端儲存連結」，以及將雲端物件匯入目前綱要的表格或外部表格。

取得證明資料程序清單

傳回可用的證明資料清單

Ingest.get_credential_list()

上述函數會傳回「證明資料」清單。

範例

在此範例中，您可以取得所有「證明資料」：

adp.Ingest.get_credential_list()
 
{
  "items": [
    {
      "credential_name": "PROVIDER_DEMO_DELTA_SHARING_111$SHARE_CRED",
      "username": "BEARER_TOKEN",
      "windows_domain": null,
      "comments": "{\"comments\": \"Created via DBMS_CLOUD.create_credential\",\"user_comments\": \"\"}"
    },
    ...
    ]
}

建立證明資料程序

建立簡單證明資料。對於 Microsoft Azure 雲端，使用帳戶名稱和密碼是存取金鑰，Amazon 使用者是存取金鑰 ID，密碼是秘密存取金鑰，Google 使用者是 HMAC 存取金鑰，密碼是 HMAC 存取加密密碼。

語法

Ingest.create_credential(credential_name, user, password)

參數：

credential_name ：新證明資料的名稱
user 和 password 取決於雲端系統：Microsoft Azure 雲端 user 是帳戶名稱，而 password 是存取金鑰，Amazon user 則是存取金鑰 ID， password 則是 Google user 的秘密存取金鑰為 HMAC 存取金鑰，而 password 則是 HMAC 存取加密密碼。

範例

在此範例中，您可以使用指定的使用者和密碼來建立證明資料：

adp.Ingest.create_credential('TEST", 'ADMIN', 'PASSWORD')

建立 OCID 證明資料程序

使用 OCI 簽署金鑰建立證明資料。

語法

Ingest.create_ocid_credential(credential_name, user_ocid, tenancy_ocid,
                          private_key, fingerprint)

此函數會使用 OCI 簽署金鑰建立證明資料。

參數：

credential_name ：證明資料的名稱。
user_ocid ：使用者的 OCID。
tenancy_ocid ：租用戶的 OCID。
private_key ：RSA 金鑰組中的私密金鑰。私密金鑰會跨多行。請確定將所有新行字元都換成空格字元，然後使用產生的索引鍵。
指紋：用來存取 OCI 之 RSA 金鑰組的指紋。

範例

adp.Ingest.create_ocid_credential('OCI_NATIVE_CRED', 'ocid1.user.oc1..aaaaaaaatfn77fe3fxux3o5lego7glqjejrzjsqsrs64f4jsjrhbsk5qzndq','ocid1.user.oc1..aaaaaaaatfn77fe3fxux3o5lego7glqjejrzjsqsrs64f4jsjrhbsk5qzndq', 'MIIEogIBAAKCAQEAsbNPOYEkxM5h0DF+qXmie6ddo95BhlSMSIxRRSO1JEMPeSta0C7WEg7g8SOSzhIroCkgOqDzkcyXnk4BlOdn5Wm/BYpdAtTXk0sln2DH...', '4f:0c:d6:b7:f2:43:3c:08:df:62:e3:b2:27:2e:3c:7a')

刪除證明資料程序

刪除指定名稱的證明資料。

Ingest.drop_credential(credential_name)

參數：

credential_name ：證明資料的名稱。

範例

在此範例中，您可以刪除名稱為 'TEST' 的證明資料：

adp.Ingest.drop_credential('TEST')

取得雲端儲存連結清單程序

語法

Ingest.get_cloud_storage_link_list(owner)

參數：

擁有者：此欄位顯示「資料庫連結」的擁有者。如果沒有這個欄位，工具會使用目前的綱要擁有者。

範例

在此範例中，您可以列出「雲端儲存連結」：

Ingest.get_cloud_storage_link_list()
 
// Output
 
{
  "nodes": [
    {
      "label": "AA",
      "type": "CLOUD_STORAGE_LINK",
      "id": "\"ADMIN\".\"STORAGE_LINK\".\"AA\"",
      "data": {
        "name": "AA",
        "entityID": 28897,
        "namespace": "STORAGE_LINK",
        "path": "\"STORAGE_LINK\".\"AA\"",
        "schema": "ADMIN",
        "application": "CLOUD",
        "created": "2023-01-30T21:42:17Z",
        "updated": "2023-01-30T21:42:17Z",
        "catalog": "LOCAL"
      }
    },
    ...
    ]
}

建立雲端儲存連結程序

根據雲端儲存 URI 和證明資料建立雲端儲存連結程序。如果儲存連結是公用儲存桶，則可以略過證明資料。

語法

Ingest.create_cloud_storage_link(storage_link_name, uri, credential_name,
                          description)

參數：

storage_link_name ：雲端儲存連結的名稱。您必須在此欄位中輸入值。
URI ：檔案名稱以外的 URL 路徑 (URI)。您必須在此欄位中輸入值。
credential_name ：證明資料名稱必須符合 Oracle 物件命名慣例。
說明：連結的說明。如果缺少說明，此工具會改用 storage_link_name 。

範例

在此範例中，您可以建立名稱為 'TEST' 的雲端儲存連結

Ingest.create_cloud_storage_link('TEST', 'https://.../test-bucket/o/', None, 'OCI Storage Link')

刪除雲端儲存連結程序

根據儲存連結名稱刪除雲端儲存連結。

Ingest.drop_cloud_storage_link(storage_link_name)

參數：

storage_link_name ：雲端儲存連結的名稱。

範例

在此範例中，您可以刪除名稱為 'TEST' 的雲端儲存連結

Ingest.drop_cloud_storage_link('TEST')

取得雲端儲存物件程序

取得雲端儲存連結中的物件清單。

語法

Ingest.get_cloud_objects(storage_link,owner)

此函數會傳回雲端儲存連結中的物件清單。

參數：

storage_link ：雲端儲存連結的名稱。
擁有者：此欄位顯示「資料庫連結」的擁有者。如果沒有這個欄位，工具會使用目前的綱要擁有者。

範例

在此範例中，您可以列出名稱為 'TEST' 之雲端儲存連結中的物件

Ingest.get_cloud_objects('TEST')
 
// Output
{
"nodes": [
     {
      "label": "users/1623813236395.parquet",
      "type": "CLOUD_OBJECT",
      "id": "\"ADMIN\".\"STORAGE_LINK\".\"TEST\".\"OBJECT\".\"users/1623813236395.parquet\"",
      "data": {
        "name": "users/1623813236395.parquet",
        "namespace": "OBJECT",
        "path": "\"STORAGE_LINK\".\"TEST\".\"OBJECT\".\"users/1623813236395.parquet\"",
        "schema": "ADMIN",
        "annotation": {
          "bytes": 1835742,
          "checksum": "8c215516638037427850b03f0e111850",
          "isFolder": false,
          "fileName": "1623813236395.parquet",
          "uri": "https://.../test-bucket/o/users/1623813236395.parquet"
        },
        "application": "CLOUD",
        "created": "2022-08-02T14:21:26Z",
        "updated": "2022-08-02T14:21:26Z",
        "catalog": "LOCAL"
      }
    },...
    ]
}

這會傳回可用的用戶群組清單。

複製雲端物件程序

將雲端物件從雲端儲存連結複製到目前綱要中的表格

Ingest.copy_cloud_objects(objects, consumer_group)

參數：

物件：表格描述的陣列。每個描述都有 4 個欄位。
- storageLink ：雲端儲存連結的名稱。您必須在此欄位中輸入值。
- objectName ：雲端儲存連結中的檔案名稱。請參閱 get_cloud_object 方法結果中的 name 欄位。您必須在此欄位中輸入值。
- targetTableName ：目標表格的名稱。如果缺少此欄位，則工具會使用檔案名稱作為表格名稱。
consumer_group ：用戶群組。預設值為 "LOW"。

範例

在此範例中，您可以在「雲端儲存連結」中建立表格並從物件載入資料。

adp.Ingest.copy_cloud_objects([{'storageLink': 'TEST', 'objectName': 'users/testData.csv','targetTableName': 'TESTDATA'}, 'HIGH')
 
output:
[
  {
    "storageLink": "TEST",
    "targetTableName": "TESTDATA",
    "objectName": "users/testData.csv",
    "rowsCopied": 588
  }
]

連結雲端物件程序

根據雲端儲存連結的雲端物件建立外部表格。

Ingest.link_cloud_objects(objects, consumer_group)

參數：

物件：表格描述的陣列。每個描述都有 4 個欄位。
- storageLink ：雲端儲存連結的名稱。您必須在此欄位中輸入值。
- objectName ：雲端儲存連結中的檔案名稱。請參閱 get_cloud_object 方法結果中的 name 欄位。您必須在此欄位中輸入值。
- targetTableName ：目標表格的名稱。如果缺少此欄位，則工具會使用檔案名稱作為表格名稱。
consumer_group ：用戶群組。預設值為 "LOW"。

範例

在此範例中，您可以從「雲端儲存連結」中的指定物件建立外部表格。

adp.Ingest.link_cloud_objects([{'storageLink': 'TEST', 'objectName': 'users/testData.csv','targetTableName': 'TESTDATA'}, 'HIGH')
 
output:
[
  {
    "storageLink": "TEST",
    "targetTableName": "TESTDATA",
    "objectName": "users/testData.csv",
    "rowsCopied": 588
  }
]

從 json 資料程序建立表格

Ingest.load_data(tables)

參數：

表格是含有下列欄位的字典的清單：
- content ：這是資料內容，以索引鍵作為資料欄名稱，並以值作為資料欄值清單。
- targetTableName ：表格的名稱。

範例

在此範例中，您可以建立表格並使用來自內容的資料填入表格：

content = {
"Year_id":[11,12,13,14,15],
"Year_name": ["CY2011","CY2012","CY2013","CY2014","CY2015"],
"Year_end_date": ["31-DEC-11","31-DEC-12","31-DEC-13","31-DEC-14","31-DEC-15"],
"Quarter_id":[211,212,213,214,215],
"Quarter_name":["Q2CY2011","Q2CY2012","Q2CY2013","Q2CY2014","Q2CY2015"],
"Quarter_end_date":["30-JUN-11","30-JUN-12","30-JUN-13","30-JUN-14","30-JUN-15"]
}
  
content_list=[{"content": content, "targetTableName": "TestLoad"}]
  
adp.Ingest.load_data(content_list)
  
  
//Output
  
[{'fileName': 'TESTLOAD', 'targetTableName': 'TESTLOAD', 'rowsCopied': 6}]

父項主題：使用 Python Data Studio API for Autonomous Database