摄取函数

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 》中的 "Database Links Database Links "。

Ingest.get_database_links(owner)

参数：

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 个字段。
owner（所有者）：此字段显示数据库链接的所有者。如果缺少此字段，该工具将使用当前模式所有者。
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 个字段
- owner（所有者）：此字段显示数据库链接的所有者。如果缺少此字段，该工具将使用当前模式所有者。
- 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'}
]

云存储链路操作

Cloud Storage Link 函数为 Data Studio 工具套件的 Cloud Storage Link 工具提供了应用程序编程接口的类、方法、属性和参数的语法和说明。

这些方法允许管理身份证明和云存储链接，并将云对象导入当前方案的表或外部表。

获取身份证明列表过程

返回可用身份证明列表

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)

参数：

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 对象命名约定。
description（说明）：链接的说明。如果缺少说明，该工具将改用 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')

获取云存储对象过程

获取 Cloud Storage Link 中的对象列表。

语法

Ingest.get_cloud_objects(storage_link,owner)

此函数返回云存储链接中的对象列表。

参数：

storage_link ：云存储链路的名称。
owner（所有者）：此字段显示数据库链接的所有者。如果缺少此字段，该工具将使用当前模式所有者。

示例

在此示例中，可以列出 Cloud 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"。

示例

在此示例中，可以在 Cloud Storage Link 中创建表并加载对象中的数据。

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"。

示例

在此示例中，可以在 Cloud Storage Link 中基于指定的对象创建外部表。

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}]

父主题：使用适用于 Autonomous Database 的 Python Data Studio API