PL/SQLでのData Studioデータ・ロードAPIの使用 (2024/06/29)

PL/SQLでのData Studioデータ・ロードAPIの使用 (2024/06/29)

https://blogs.oracle.com/datawarehousing/post/data-studio-data-load-apis-plsql

投稿者： William Endress | Autonomous Database Product Management


はじめに


Data Studioデータ・ロード・アプリケーションは、強力で使いやすいデータ・ロード・アプリケーションを提供し、ユーザーはコーディングなしでObject Storageから様々なファイル形式をロードできます。このアプリケーションで使用されるものと同じREST APIが文書化され、アプリケーション開発者が使用できます。REST Data Services APIを使用したデータ・ロード後のこのことについて最後に書きましたが、CURLを使用した簡単な例を提供します。


この投稿では、クラウド・ストレージ・リンクの作成、入力データの調査、データ・ロード・ジョブの作成、およびPL/SQLの進行状況の監視の例を示します。



Data Studioデータ・ロードAPIを使用する利点


Data Studioデータ・ロード・アプリケーションを使用して、データ・ロードを実行するために生成されたSQLを確認したとします。その場合、データ・ロード・ツール、つまりAPIがDBMS_CLOUDの上に階層化されていることがわかります。その後、Data Studio APIがDBMS_CLOUDを上回るメリットについて疑問に思うかもしれません。利点はたくさんあります!以下はほんの少しです:


  • Data Studio APIは、オブジェクト・ストア上のファイルを自動的に調査し、DBMS_CLOUD.COPY_DATAおよびCREATE_EXTERNAL_TABLE (フィールド・リスト、列リストおよびフォーマット・パラメータ)への入力を提供します。
  • Data Studio APIは、データ・ロード・ジョブをバックグラウンド・プロセスとして自動的に実行するようにスケジュールします。これはステートレスREST APIに必要ですが、バックグラウンドで実行時間が長い操作を実行する機能は、PL/SQLベースのアプリケーションにも非常に役立ちます。
  • Data Studioはジョブを自動的にログに記録し、ジョブの進捗を追跡するためのAPIを提供します。
  • Data Studio APIを使用すると、後で再利用できるように、名前クラウド・ストア・リンク(クラウド・ストアURIおよび資格証明)を作成できます。


それらはほんの数です。時間が節約され、DBMS_CLOUDへのコールの設定から推測が不要になるため、お気に入りはサーベイ・エンドポイントです。DBMS_CLOUD.COPY_DATAは手作業で行ったことがありません。



PL/SQLを使用したREST APIの実行


REST APIは、Webベースのアプリケーションの基盤として知られていますが、PL/SQLでREST APIをどれほど簡単に使用できるかはわかりません。必要なのは、Webリクエストの作成、レスポンスの受信、およびJSONオブジェクトからのデータの抽出方法を知るためのPL/SQLファンクションのみです。幸いなことに、Oracleは両方を提供します。同僚のNilay Panchal氏は、Autonomous Database内からOracle Function(または任意のクラウドREST API)をレベルアップして呼び出す方法について、自分の投稿でDBMS_CLOUD.SEND_REQUESTの使用について書きました。APEXでかなりの時間を過ごすので、例でAPEX_UTIL.MAKE_WEB_REQUESTを使用します。REST APIを使用する場合、JSON_VALUE、JSON_TABLE、JSON_OBJECTなどのOracle JSON関数の知識が必要です。


APEX_UTIL.MAKE_WEB_REQUESTの使用は、非常にストレート形式です。次の形式を使用します。


DECLARE
  v_response CLOB;
BEGIN
  v_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST (
    p_url => 'endpoint url'
    , p_username => 'database username'
    , p_password => 'database user password'
    , p_body => 'body');
  RETURN v_response;
END;


サンプル・スクリプト


データ・ロードの各ステージを実行するPL/SQLスクリプトを作成することは非常に簡単です。次のスクリプト:


  1. 事前認証済リクエスト(PAR)を使用してクラウド・ストレージ・リンクを作成します。
  2. サーベイを実行してデータファイルを検査します。
  3. データ・ロード・ジョブを作成します。
  4. データ・ロード・ジョブの進捗を取得します。


次のサンプル・スクリプトは、クラウド・ストアの場所を作成し、データ・ロード・ジョブを作成し、ジョブの進行状況を確認します。



クラウド・ストア・リンクの作成


クラウド・ストレージ・リンクは、名前付きクラウド・ストアURIであり、必要に応じて資格証明名です。この例では事前認証済リクエストを使用するため、資格証明は必要ありません。


DECLARE
  v_response CLOB;
  v_base_url VARCHAR2(1000);
  v_database_user VARCHAR2(100);
  v_password VARCHAR2(100);
  v_url VARCHAR2(1000);
  v_body CLOB;
BEGIN

  -- The name of your database user (schema) and password.
  v_database_user := 'your_user';
  v_password := 'your_password';

  -- The URL to your Autonomous Database instance.  Note: Do not include a / at the end.
  v_base_url := 'https://xxxxxx.oraclecloudapps.com';

  -- The URL used in the web request (no substitutions required).
  v_url := v_base_url || '/ords/' || LOWER(v_database_user) || '/_/db-api/stable/data-tools/cloud-storage-links/';

 -- Parameters to the cloud store link (no substitutions required).
v_body :=
  '{
     "cloud_storage_links":[
        {
          "storage_link_name":"FUEL_PRICES",
          "storage_link_description":"Preauthenicated request to Oracle object store bucket",
          "uri":"https://objectstorage.uk-london-1.oraclecloud.com/p/QLkz12KR7fmHrp_REIU4s1pVxoybjv-nyxU1hbPajogTbR8iTeJGsAr556yTMVrw/n/adwc4pm/b/blog_data/o/"
       }
     ]
  }';

  -- Make the web request to create the cloud storage link.
  v_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
    p_url => v_url
    , p_http_method => 'POST'
    , p_username => v_database_user
    , p_password => v_password
    , p_body => v_body);

  -- Print the response to the screen.
  DBMS_OUTPUT.PUT_LINE (v_response);

END;
/


サーベイ入力データおよびデータ・ロード・ジョブの作成


データ・ロード・ジョブの作成は、次の2つの部分からなるプロセスです。


  1. 入力データを調査します(フォーマット、列リストおよびフィールド・リストを取得します)。
  2. データ・ロード・ジョブを作成します。


DECLARE
  v_survey CLOB;
  v_response CLOB;
  v_base_url VARCHAR2(1000);
  v_database_user VARCHAR2(100);
  v_password VARCHAR2(100);
  v_url VARCHAR2(1000);
  v_body CLOB;
BEGIN

  -- The name of your database user (schema) and password.
  v_database_user := 'your_user';
  v_password := 'Oracle123456';

  -- The URL to your Autonomous Database instance. Note: Do not include a / at the end.
  v_base_url := 'https://xxxxxx.oraclecloudapps.com';

  -- The URL used in the survey web request (no substitutions required).
  v_url := v_base_url || '/ords/' || LOWER(v_database_user) || '/_/db-api/stable/data-tools/surveys/';

 -- Create the body to the survey web request.  Note that in this example
-- 'd1925/' is a folder within the cloud store bucket.
   v_body :=
   '{
      "data_loads":[
        {
          "storage_link_name":"FUEL_PRICES",
          "objects":[
            {
               "object_name":"d1925/"
            }
         ],
         "table_name":"FUEL_PRICES_TABLE"
        }
      ]
    }';

  -- Make the survey web request. 
  v_survey := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
    p_url => v_url
    , p_http_method => 'POST'
    , p_username => v_database_user
    , p_password => v_password
    , p_body => v_body);

    DBMS_OUTPUT.PUT_LINE (JSON_QUERY(v_survey, '$' RETURNING CLOB PRETTY) );

  -- The URL used in the create data load job web request.
   v_url := v_base_url || '/ords/' || LOWER(v_database_user) || '/_/db-api/stable/data-tools/data-loads/';    

  -- Make the create load job request.   Note the previous survey response is
  -- the body to the create data load job request.

  v_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
    p_url => v_url
    , p_http_method => 'POST'
    , p_username => v_database_user
    , p_password => v_password
    , p_body => v_survey);   
  
  -- Print the response to the screen.
  DBMS_OUTPUT.PUT_LINE (JSON_QUERY(v_response, '$' RETURNING CLOB PRETTY) );

END;
/


データ・ロード・ジョブのステータスの確認


データ・ロード・ジョブのステータスを確認します。ジョブ・リクエストの作成レスポンスのdata_load_idに注意してください。


DECLARE
  v_response CLOB;
  v_base_url VARCHAR2(1000);
  v_database_user VARCHAR2(100);
  v_password VARCHAR2(100);
  v_job_id INT;
  v_url VARCHAR2(1000);
BEGIN

  -- The name of your database user (schema) and password.
  v_database_user := 'your_user';
  v_password := 'your_password';

  -- The URL to your Autonomous Database instance. Note: Do not include a / at the end.
  v_base_url := 'https://xxxxxx.oraclecloudapps.com';
 
  -- Substitute your job id.
  v_job_id := 21947;

  -- The URL used in the survey web request (no substitutions required).
  v_url := v_base_url || '/ords/' || LOWER(v_database_user) || '/_/db-api/stable/data-tools/data-loads/' || v_database_user || ',' || v_job_id || '/progress';
 
  -- Make the progress web request. 
  v_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
    p_url => v_url
    , p_http_method => 'GET'
    , p_username => v_database_user
    , p_password => v_password);

  -- Print the response to the screen.  
  DBMS_OUTPUT.PUT_LINE (JSON_QUERY(v_response, '$' RETURNING CLOB PRETTY) );  
END;
/


表の問合せ


この仕事は小さくて速く走るだろう。これで、表を問い合せることができます。


SELECT * FROM FUEL_PRICES_TABLE;


APIレスポンスからの選択


WebリクエストはJSONオブジェクトを返します。PL/SQLで作業している場合は、JSONからデータを問い合せたり、抽出する必要があります。プロのヒント:  生成AIは、通常、JSONオブジェクトを使用したOracle JSON関数の優れた例を提供します。「Oracle JSON_TABLEの使用」などのプロンプトを使用して、次のJSONオブジェクトからtable_name、column_name、field_nameを選択します:  {ここにオブジェクトを貼り付けます。}


次に例を示します。


サーベイ応答


表としてサーベイ応答から選択します。


SELECT
  table_name
  , column_name
  , field_name
  , data_type
  , data_length
  , data_format
  , column_id
FROM
    JSON_TABLE ({your survey response}, '$.data_loads[*]'
      COLUMNS (
        table_name VARCHAR2 ( 100 ) PATH '$.table_name'
      , NESTED PATH '$.columns[*]'
          COLUMNS (
            column_name VARCHAR2 ( 500 ) PATH '$.column_name'
          , field_name VARCHAR2 ( 500 ) PATH '$.field_name'
          , data_type VARCHAR2 ( 500 ) PATH '$.data_type'
          , data_length NUMBER PATH '$.data_length'
          , data_format VARCHAR2 ( 500 ) PATH '$.data_format'
          , column_id NUMBER PATH '$.column_id'
          )
      )
    )
  jt;


調査応答から値ignoremissingcolumnsを抽出します。


JSON_VALUE(json_column, '$.data_loads[0].format.ignoremissingcolumns' RETURNING BOOLEAN)


進捗応答


表として進捗応答から選択します。


SELECT
    owner
    , data_load_job_id
    , table_name
    , rows_loaded
    , rows_rejected
    , rows_total
    , estimated_total_rows
    , percentage_completed
    , status
    , time_start 
    , time_completion
    , exception_details
    , last_event VARCHAR2
    , time_of_last_event
FROM
    JSON_TABLE ( '{your progess response}', '$.items[*]'
      COLUMNS (
        owner VARCHAR2 ( 20 ) PATH '$.owner'
      , data_load_job_id NUMBER PATH '$.data_load_job_id'
      , table_name VARCHAR2 ( 30 ) PATH '$.table_name'
      , rows_loaded NUMBER PATH '$.rows_loaded'
      , rows_rejected NUMBER PATH '$.rows_rejected'
      , rows_total NUMBER PATH '$.rows_total'
      , estimated_total_rows VARCHAR2 ( 10 ) PATH '$.estimated_total_rows'
      , percentage_completed NUMBER PATH '$.percentage_completed'
      , status VARCHAR2 ( 20 ) PATH '$.status'
      , time_start TIMESTAMP PATH '$.time_start'
      , time_completion TIMESTAMP PATH '$.time_completion'
      , exception_details VARCHAR2 ( 100 ) PATH '$.exception_details'
      , last_event VARCHAR2 ( 20 ) PATH '$.last_event'
      , time_of_last_event TIMESTAMP PATH '$.time_of_last_event'
      )
    )
  jt;


進捗応答から単一値を抽出するエクスプレス。


JSON_VALUE({your progess response},'$.items[0].percentage_completed')



まとめ



Oracle Autonomous Data Studioのデータ・ロードAPIを使用すると、データ・ロード・ジョブの定義と実行が非常に簡単になります。APIは、データベース提供のパッケージを使用してPL/SQL内からWebリクエストとして実行できるため、これらの重要なAPIを利用するスクリプトおよびアプリケーションを構築できます。


コメント

コメントを投稿

このブログの人気の投稿

Oracle Database 19cサポート・タイムラインの重要な更新 (2024/11/20)

イメージ
Oracle Database 19cサポート・タイムラインの重要な更新 (2024/11/20) https://mikedietrichde.com/2024/11/20/important-update-to-oracle-database-19c-support-timelines/ 長い沈黙は、私が隠れているという意味ではありません。つまり、今はとても忙しいということです。そして、より少ない旅行で、私はあなたのコメントにもブログと返信するより多くの時間を持っていることを願っています。それでも、Oracle Database 19cサポート・タイムラインの非常に重要な更新について説明します。 * 更新された内容 2024年11月19日現在、Oracle Database 19cのサポート・タイムラインが調整されています。 MOSノート: 742060.1 – 現在のデータベース・リリースのリリース・スケジュールを見ると、新しい日付が表示されます。 Premier Support、2029年12月31日まで 2030年1月1日から2032年12月31日までの拡張サポート 2033年1月1日から2034年12月31日までのアップグレード・サポート これは知ることがとても大切です。 他のリリースの更新はありますか。 MOSノートの終わりにある変更ログ: 742060.1 – 現在のデータベース・リリースのリリース・スケジュールでは、Oracle Database 21cの最新の更新も確認できます。このリリースのPremier Support期間は、2027年7月31日まで延長されました。 また、Oracle Database 23aiのパッチ適用終了日は2032年12月31日に設定されています。 Lifetime Support Policy 更新は、Oracle Technology Productsの Oracle Lifetime Support Policy (6ページ)でも確認できます。 From: Oracle Lifetime Support Policy for Oracle Technology Product s – page 6 – Nov 19, 2024 特に、次の表に示す制限事項に注意してください。 Oracle Database 1...
続きを読む

Oracle APEXのInteractive Gridで、Oracle Formsと比較して、重複行の検証を制御/通過させる方法 (2022/07/21)

イメージ
Oracle APEXのInteractive Gridで、Oracle Formsと比較して、重複行の検証を制御/通過させる方法 (2022/07/21) https://medium.com/oracledevs/how-to-control-or-pass-validation-for-duplicate-rows-in-interactive-grid-of-oracle-apex-as-compare-18f453f750bf 投稿者： Jignesh oracle Formsでは、データブロックの重複行を制御するのは非常に簡単ですが、IGの検証を制御するにはどうすればよいでしょうか。 必要な出力 ステップ1：インタラクティブグリッドのある白紙ページを作成します（私は1つの領域「IG」を作成し、インタラクティブグリッドとしてタイプを選択しました） ステップ 2: リージョンに Static ID を定義する (私の場合、リージョンは IG で、Static ID も IG です) ステップ3：複製を制御したいカラムのStatic IDを定義します ステップ4：関数とグローバル変数に移動します コード： var validity, message, ui = this.data; (function($) { function update(model) { var projKey = model.getFieldKey(“PROJECT_ID”), recObj = [], recArray = []; model.forEach(function(record, index, id) { var projid = parseInt(record[projKey], 10), // record[salKey] should be a little faster than using model.getValue in a loop meta = model.getRecordMetadata(id); if (!isNaN(projid) && !meta.deleted && !meta.agg) { recObj = {ID: id, project_id: projid}; recArray.push(recObj)...
続きを読む

Oracle APEX 24.1の一般提供の発表 (2024/06/17)

イメージ
Oracle APEX 24.1の一般提供の発表 (2024/06/17) https://blogs.oracle.com/apex/post/announcing-oracle-apex-241 投稿者： Ashish Mohindroo | Vice President, Product Management APEX Low Code Application Platform Oracle APEX 24.1は、 ダウンロード が一般的に可能になり、世界中のOCI APEX Application DevelopmentおよびAutonomous Database Cloud Serviceリージョンにロールアウトされています。この最新リリースで、GenAIを使用して最初のローコード・アプリケーションを構築する方法を学習します。リリースのお知らせのリプレイはこちらからご覧いただけます。 このリリースでは、優れたエンタープライズ・グレードのアプリケーションを簡単に構築できるイノベーションの3つの主要な柱(AI支援アプリケーション開発、Oracleの次世代データ・プラットフォームのパワー活用、高度なWebおよびモバイル・アプリケーションを構築するための強力なエンタープライズ・グレードのコンポーネント)が提供されています。 AI支援アプリ開発 このリリースでは、AIをローコード開発に直接取り込み、すべての開発者が高度なクラウドおよびモバイル・アプリケーションを簡単に構築できるようにしています。開発者は、AIをアシスタントとして使用して、時間と労力を削減してアプリを構築できるようになりました。APEX AIアシスタントを使用すると、開発者は複数のウィンドウを使用して表名と列名を検索する必要がなくなります。 APEX 24.1 では、クラウドおよびモバイル・アプリの自然言語ベースの開発を可能にするネイティブAI搭載APEX AIアシスタントを導入しました。APEX AIアシスタントを使用すると、すべての開発者は自然言語を使用してSQLを生成できるため、アプリケーションをより簡単に構築したり、ワンクリックで構文修正を実行したり、表名を覚える必要がなくなります。開発者は、自然言語プロンプトを使用して目的の機能とコンポーネントを指定し、直感的な会話型インタフェースを使用し...
続きを読む