1. Oracle Cloudの使用ガイド
  2. データ・ツール
  3. Oracle Autonomous Database用のPython Data Studio API
  4. Autonomous Database用のPython Data Studio APIの使用
  5. 取込み関数

11.1.1 取込み関数

Adp.Ingestクラスは、様々なソースから表およびビューにデータをロードするために使用されます。

Autonomous Database Load Data API for Pythonでは、次の操作が可能です:

  • データベース・リンクから現在のスキーマの表またはビューへの表のコピー
  • クラウド・ストレージ・リンクから現在のスキーマの表または外部表へのオブジェクトのコピー
  • jsonからのデータを含む表の作成

これらの操作により、対応する取込みジョブが作成されます

データベース・リンク操作

これらのメソッドは、データベース・リンクから現在のスキーマへの表のインポートに使用されます。

Ingest.get_consumer_groups()

この関数は、使用可能なコンシューマ・グループのリストを返します。

Ingest.get_database_links(owner=None)

この関数は、使用可能なデータベース・リンクのリストを返します。

Ingest.get_db_link_owner_tables(db_link)

これは、データベース・リンクから表およびビューのリストを返します。リストの各レコードには次のフィールドがあります:

{'dbLink': dbLink, 'owner':owner, 'tableName': tableName, 'numRows':numRows, 'avgRowLen':averageRowLength} 

Ingest.copy_tables_from_db_link(tables)

この関数は、指定された表から現在のデータベースにデータをロードします。tablesは、次のフィールドを含むディクショナリのリストです。

{'owner':owner, 'tableName':tableName, 'dbLink':dbLink, 'targetTableName':targetTableName}

最初の3つのフィールドはgetDBLinkOwnerTables関数から取得でき、targetTableNameフィールドはオプションです。欠落しているか、Noneと等しい場合は、表名としてtableNameを使用します。処理中に、現在のデータベースにすでにこの表がある場合、ターゲット表の名前がわずかに変更されることがあります。たとえば、DATAの元の表が存在する場合は、かわりに、メソッドによってレコードがDATA_1表にコピーされます。

このメソッドは、作成する表のリストを返します。出力のディクショナリは入力パラメータと同じで、追加の値には行数が挿入されます。

Ingest.link_tables_from_db_link(tables)

この関数は、指定された表から現在のデータベースにビューを作成します。tablesは、次のフィールドを含むディクショナリのリストです:

{'owner':owner, 'tableName':tableName, 'dbLink':dbLink, 'targetTableName':targetTableName}

最初の3つのフィールドはgetDBLinkOwnerTables関数から取得でき、targetTableNameフィールドはオプションです。欠落しているか、Noneと等しい場合は、ビュー名としてtableNameを使用します。

クラウド・ストレージ・リンク操作

これらの方法では、資格証明およびクラウド・ストレージ・リンクの管理、および現在のスキーマの表または外部表へのクラウド・オブジェクトのインポートが可能です。

Ingest.get_credential_list()

前述の関数は、資格証明のリストを返します。

次に、パラメータとその説明を示します:
  • credential_name: 資格証明の名前です。
  • user: ユーザー名を指定します。
  • password: パスワードを指定します。
    • Microsoft Azureクラウドの場合、userはaccount name、passwordはaccess keyです。
    • Amazonの場合、userはaccess key ID、passwordはsecret access keyです。
    • Googleの場合、userはHMAC access key、passwordはHMAC access secretです。 

Ingest.create_credential(credential_name, user, password)

この関数は資格証明を作成します。

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

この関数は、OCI署名キーを使用して資格証明を作成します。

次に、パラメータとその説明を示します:

  • storage_link_name: クラウド・ストレージ・リンクの名前を指定します。

  • user_ocid: ユーザーのOCID。
  • tenancy_ocid: テナンシのOCID。
  • auth_user: OCIユーザー名。
  • private_key: RSAキー・ペアの秘密キー。秘密キーは複数の行にまたがります。すべての改行文字をスペース文字で置き換え、その結果のキーを使用してください。
  • fingerprint: OCIへのアクセスに使用しているRSAキー・ペアのフィンガープリント。 

Ingest.drop_credential(credential_name)

この関数は資格証明を削除します。

credential_name: 資格証明の名前を指定します。 

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

この関数は、クラウド・ストレージ・リンクを作成します。

次に、パラメータとその説明を示します:

  • storage_link_name: クラウド・ストレージ・リンクの名前を指定します。

  • uri: ファイル名を除くURLパス(URI)を指定します。
  • credential_name: 資格証明名は、Oracleオブジェクトの命名規則に準拠している必要があります。
  • description: リンクの説明を指定します。説明がない場合は、かわりにstorage_link_nameが使用されます。ストレージ・リンクがパブリック・バケットの場合、資格証明はスキップされます。 

Ingest.get_cloud_storage_link_list(self, owner : str = None)

この関数は、クラウド・ストレージ・リンクのリストを返します。

次に、パラメータとその説明を示します:

  • owner: クラウド・ストレージ・リンクのスキーマ名を指定します。 

Ingest.drop_cloud_storage_link(storage_link_name)

storage_link_name: クラウド・ストレージ・リンクの名前を指定します。 

Ingest.get_cloud_objects(storage_link,owner)

この関数は、クラウド・ストレージ・リンク内のオブジェクトのリストを返します。

ownerフィールドには、データベース・リンクの所有者が表示されます。このフィールドがない場合、現在のスキーマ所有者が使用されます。 

Ingest.get_consumer_groups()

使用可能なコンシューマ・グループのリストが返されます。

Ingest.copy_cloud_objects(objects, consumer_group='LOW')

この関数は、クラウド・ストレージ・リンクから現在のスキーマ内の表にクラウド・オブジェクトをコピーします。

オブジェクトは、次のフィールドを含むディクショナリのリストです:

{'storageLink': storageLink, 'objectName':objectName, 'targetTableName': targetTableName}

次に、パラメータとその説明を示します:

storageLink: これはクラウド・ストレージ・リンクです。

objectName: これは、クラウド・ストレージ・リンク内のオブジェクトの名前です。

targetTableName: これは、作成する表の名前です。

consumerGroup: これは、クラウド・オブジェクトのコピー時のパフォーマンスおよび同時実行性のレベルを定義するコンシューマ・グループの1つです。コンシューマ・グループの使用可能な名前は、HIGH、MEDIUMおよびLOWです。 

Ingest.link_cloud_objects(objects, consumer_group='LOW')

クラウド・ストレージ・リンクからのクラウド・オブジェクトに基づいて外部表が作成されます。

オブジェクトは、次のフィールドを含むディクショナリのリストです:

{'storageLink': storageLink, 'objectName':objectName, 'targetTableName': targetTableName}

storageLink: これはクラウド・ストレージ・リンクです。

objectName: これは、クラウド・ストレージ・リンク内のオブジェクトの名前です。

targetTableName: 作成された表の名前です。

consumer_group: これは、クラウド・オブジェクトのコピー時のパフォーマンスおよび同時実行性のレベルを定義するコンシューマ・グループの1つです。コンシューマ・グループの使用可能な名前は、HIGH、MEDIUMおよびLOWです。

前述の関数は、取込みジョブの説明を返します。重要なパラメータはrequestIdで、これは完了の確認に使用されます。

jsonデータからの表の作成

Ingest.load_data(tables)

前述の関数は、指定されたコンテンツから現在のデータベースにデータをロードします。tablesは、次のフィールドを含むディクショナリのリストです:

{'content:content, 'targetTableName':targetTableName}

contentはデータの内容で、キーが列名、値が列の値リストであるディクショナリです。

このメソッドは、作成された表のリストを返します。出力のディクショナリは、表名と挿入された行数です。

データ・ロードの例

この項では、データ・ロードAPIの使用方法を理解するために有効な例を示します:

  • データベース・リンク表からのデータベース表の作成
  • データベース・リンク表からのデータベース・ビューの作成
  • クラウド・ストレージ・リンクの作成
  • クラウド・ストレージ・リンク内のクラウド・オブジェクトからのデータベース表の作成
  • クラウド・ストレージ・リンク内のクラウド・オブジェクトからのデータベース外部表の作成

これらの例を使用する前に、ADPインスタンスを作成してAutonomous Databaseに接続する必要があります:

import adp
adp_instance = adp.login('<protocol://host:port>', 'schema_name', 'schema_password')

データベース・リンク表からのデータベース表の作成

すべてのデータベース・リンクのリストを受け取ります。

adp_instance.Ingest.get_database_links()
 
output:
{
  "nodes": [
    {
      "label": "ABCD_ORDS_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
      "type": "DB_LINK",
      "id": "\"ADPTEST\".\"DB_LINK\".\"ABCD_ORDS_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM\"",
      "data": {
        "name": "ABCD_ABCD_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
        "namespace": "DB_LINK",
        "path": "\"DB_LINK\".\"ABCD_XXXX_SH.ABCD.RDBMS.XXX.US.ORACLE.COM\"",
        "schema": "ADPTEST",
        "application": "DATABASE",
        "created": "2022-08-14T07:58:57Z",
        "updated": "2022-08-14T07:58:57Z"
      }
    }
  ],
  "links": []
}

データベース・リンクの表のリストを受け取ります。

adp_instance.Ingest.get_db_link_owner_tables('ABCD_ADP_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM')
 
output:
 
{
  "CAL_MONTH_SALES_MV": {
    "dbLink": "ABCD_ADP_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "CAL_MONTH_SALES_MV",
    "numRows": 35,
    "avgRowLen": 23
  },
  "CHANNELS": {
    "dbLink": "ABCD_ADP_SH.REGRESS.ABCDE.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "CHANNELS",
    "numRows": 5,
    "avgRowLen": 20
  },
  "COSTS": {
    "dbLink": "ABCD_XXXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "COSTS",
    "numRows": 960,
    "avgRowLen": 19
  },
  "COUNTRIES": {
    "dbLink": "ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "COUNTRIES",
    "numRows": 19,
    "avgRowLen": 33
  },
  "CUSTOMERS": {
    "dbLink": "ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "CUSTOMERS",
    "numRows": 630,
    "avgRowLen": 139
  },
  "DIMENSION_EXCEPTIONS": {
    "dbLink": "ABCD_XXXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "DIMENSION_EXCEPTIONS",
    "numRows": 0,
    "avgRowLen": 0
  },
  "FWEEK_PSCAT_SALES_MV": {
    "dbLink": "ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "FWEEK_PSCAT_SALES_MV",
    "numRows": 934,
    "avgRowLen": 70
  },
  "MV_CAPABILITIES_TABLE": {
    "dbLink": "ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "MV_CAPABILITIES_TABLE",
    "numRows": 0,
    "avgRowLen": 0
  },
  "PLAN_TABLE": {
    "dbLink": "ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "PLAN_TABLE",
    "numRows": 0,
    "avgRowLen": 0
  },
  "PRODUCTS": {
    "dbLink": "ABCD_XXXX_SH.ABCDE.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "PRODUCTS",
    "numRows": 766,
    "avgRowLen": 243
  },
  "PROMOTIONS": {
    "dbLink": "ABCD_XXXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "PROMOTIONS",
    "numRows": 501,
    "avgRowLen": 68
  },
  "REWRITE_TABLE": {
    "dbLink": "ABCD_ABCDE_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "REWRITE_TABLE",
    "numRows": 0,
    "avgRowLen": 0
  },
  "SALES": {
    "dbLink": "ABCD_ABCD_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "SALES",
    "numRows": 960,
    "avgRowLen": 30
  },
  "TIMES": {
    "dbLink": "ABCD_ABCDE_SH.ABCDEF.RDBMS.DEV.US.ORACLE.COM",
    "owner": "SH",
    "tableName": "TIMES",
    "numRows": 1461,
    "avgRowLen": 178
  }
}

データベース・リンク表から表を作成できます。

ords.Ingest.copy_database_tables_from_db_link([{'owner':'SH', 'tableName':'COUNTRIES', 'dbLink':'ABCD_ORDS_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
        {'owner':'SH', 'tableName':'CHANNELS', 'dbLink':'ABCD_ORDS_SH.ABCDEF.ADBCE.DEV.US.ORACLE.COM'}])
 
output:
[
  {
     "owner":"SH",
     "tableName":"COUNTRIES",
     "dbLink":"ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
     "targetTableName":"COUNTRIES",
     "rowsCopied:: 99
  },
  {
     "owner":"SH",
     "tableName":"CHANNELS",
     "dbLink":"ABCD_XXXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM",
     "targetTableName":"CHANNELS",
     "rowsCopied": 9
  }
]

クラウド・ストレージ・リンクの作成

adp_instance.Ingest.create_cloud_storage_link('ABCD', 'https://xxxxx.abcd-ashburn-1.oraclecloud.com/n/idpbzw1f44my/b/test-bucket/o/', 'ABCD', 'oracleidentitycloudservice/abcd.xxx@oracle.com', '_Ai90CAqjzCs;XM2wgZ(')

クラウド・ストレージ・リンク内のクラウド・オブジェクトからのデータベース表の作成

クラウド・ストレージ・リンク内のすべてのオブジェクトのリストを受け取れます。

adp_instance.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"
      }
    },
    ...
    ]
}

クラウド・ストレージ・リンクでオブジェクトのリストを受け取れます。

adp_instance.Ingest.get_cloud_storage_link_list()
 
output:
{
  "nodes": [
    {
      "label": "ABCD",
      "type": "CLOUD_STORAGE_LINK",
      "id": "\"ADPTEST\".\"STORAGE_LINK\".\"ABCD\"",
      "data": {
        "name": "ABCD",
        "entityID": 196,
        "namespace": "STORAGE_LINK",
        "path": "\"STORAGE_LINK\".\"ABCD\"",
        "schema": "ADPTEST",
        "application": "CLOUD",
        "created": "2022-08-15T06:57:01Z",
        "updated": "2022-08-15T06:57:01Z"
      }
    }
  ],
  "links": []
}

クラウド・ストレージ・リンク内のクラウド・オブジェクトからのデータベース表の作成

adp_instance.Ingest.copy_cloud_objects([{'storageLink':'ILIA', 'objectName':'users/weblogic/testData.csv', 'targetTableName':'TESTDATA'},
        {'storageLink':'ABCD', 'objectName':'users/weblogic/data.json'}])
 
output:
[
   ...
  {
    "tableOwner": "ADPTEST",
    "debugLevel": null,
    "tableName": "TESTDATA",
    "dropTableNames": [],
    "requestId": 214,
    "directiveId": 1,
    "credentialName": "ABCD",
    ...
  },
  {
    ...
    "tableOwner": "ADPTEST",
    "tableName": "DATA",
    "dropTableNames": [],
    "requestId": 214,
    ...
  }
]

クラウド・ストレージ・リンク内のクラウド・オブジェクトからのデータベース外部表の作成

link_cloud_objects関数を呼び出せます。 

adp_instance.Ingest.link_cloud_objects([{'storageLink':'ABCD', 'objectName':'users/weblogic/testData.csv', 'targetTableName':'TESTDATA'},
        {'storageLink':'ABCD', 'objectName':'users/weblogic/data.json'}])
 
output:
[
  {
    ...
    "tableOwner": "ADPTEST",
    "debugLevel": null,
    "tableName": "TESTDATA",
    "dropTableNames": [],
    "requestId": 215,
    "directiveId": 1,
    "credentialName": "ABCD",
    ...
  },
  {
    ...
    "tableOwner": "ADPTEST",
    "tableName": "DATA",
    "dropTableNames": [],
    "requestId": 215,
    ...
  }
]

表へのデータのロード

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"}]
 
text = adp_instance.Ingest.load_data(content_list)
 
 
Output:
 
[{'fileName': 'TESTLOAD', 'targetTableName': 'TESTLOAD', 'rowsCopied': 6}]

完全なシナリオ

次のステップでは、分析ビューの作成からインサイトの生成までの完全なシナリオを示します。

分析ビューおよびインサイトの作成

  1. ADPインスタンスを作成し、Autonomous Databaseにログインします。
    import adp
adp_instance = adp.login('<protocol://host:port>', 'schema_name', 'schema_password')
  2. サンプル表のローカル・ファイル、データベース・リンクまたはクラウド・ストレージ・リンクから表をコピーする必要があります。サンプル表を次に示します。
    adp_instance.Ingest.copy_database_tables_from_db_link([{'owner':'SH', 'tableName': 'SALES', 'dbLink':'ABCD_ORDS_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
{'owner':'SH', 'tableName': 'PRODUCTS', 'dbLink':'ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
{'owner':'SH', 'tableName': 'CUSTOMERS', 'dbLink':'ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
{'owner':'SH', 'tableName': 'TIMES', 'dbLink':'ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
{'owner':'SH', 'tableName': 'CHANNELS', 'dbLink':'ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'},
{'owner':'SH', 'tableName': 'PROMOTIONS', 'dbLink':'ABCD_XXXX_SH.REGRESS.RDBMS.DEV.US.ORACLE.COM'}])
  3. 分析ビューの作成
    adp_instance.Analytics.create('SALES')
  4. 分析ビューを一覧表示できます。
    text = adp_instance.Analytics.get_list()
  5. 分析ビューのメジャーを取得します。
    text = adp_instance.Analytics.get_measures_list('SALES_AV')
  6. インサイトを生成します。
    adp_instance.Insight.generate('SALES_AV', 'QUANTITY_SOLD')
  7. インサイト処理の完了を確認します。
    adp_instance.Insight.get_job_status('REQUEST_INSIGHT_1')

インサイトおよび分析ビューの削除

  1. ADPインスタンスを作成し、ORDSサーバーにログインする必要があります。
    import adp
adp_instance = adp.login('<protocol://host:port>', 'schema_name', 'schema_password')
  2. 次の関数を呼び出してインサイトを削除します。
    adp_instance.Insight.drop('REQUEST_INSIGHT_1')
  3. 分析ビューの削除
    adp_instance.Analytics.drop('SALES_AV')
  4. 分析ビューの表を削除します。
    adp_instance.Misc.drop_tables(['SALES','PRODUCTS','CUSTOMERS','TIMES','CHANNELS','PROMOTIONS'])