整合 Oracle Analytics 與 OCI Functions
整合 Oracle Cloud Infrastructure (OCI) Functions 與 Oracle Analytics，以便在資料流程中使用這些函數轉換資料。
關於在 Oracle Analytics 中使用 OCI Functions
您可以在 Oracle Analytics 中使用 OCI 建立的函數來轉換資料。例如，您可以使用語言轉換函數將英文文字轉換成西班牙文或德文。
您可以先在 Oracle Analytics 註冊 OCI Functions，之後任何具備「BI 服務管理員」或「DV 內容作者」權限的 Oracle Analytics 使用者便能夠在資料流程中使用這些函數。
關於在 Oracle Analytics 設定使用 OCI Functions
在 OCI 主控台中建立函數，以便在 Oracle Analytics 資料流程中使用這些函數轉換資料。
關於在 Oracle Analytics 註冊 OCI Functions
當您在 Oracle Analytics 中註冊 OCI 函數時，如果該函數在選取函數對話方塊中顯示為灰色，請檢查函數是否已設定 oac-compatible 標記且使用正確的 funcMode 值進行呼叫。
.png
關於在 Oracle Analytics 設定使用 OCI Functions
要在 Oracle Analytics 中使用的 OCI 函數必須具有 oac-compatible 標記，而且函數程式碼必須包含 funcMode 變數。請在 OCI 主控台中設定以下設定值：
- oac-compatible - 將任意形式標記新增至函數，並將其命名為
oac-compatible，然後將值設為true。
.png - funcMode - 將
funcMode變數包含在函數程式碼中。Oracle Analytics會使用funcMode=describeFunction傳送註冊 OCI 函數的要求，然後使用funcMode=executeFunction傳送呼叫 OCI 函數的要求。func.py 中的處理程式函數應以 describeFunction 或 executeFunction 模式運作。只要透過要求中的輸入變數funcMode值，即可完成此作業，如下所示。以下是計算字數的 OCI Functions 要求和回應格式 (使用 python) 範例。
funcMode = describeFunction
{ "funcMode": "describeFunction"}要求中的 funcMode 為 'describeFunction' 時，函數應傳回內含狀態 (returnCode 與 errorMessage)、輸出值 (輸出資料欄的名稱、資料類型)、參數 (輸入參數的名稱、描述、類型等等) 及 bucketName 等的函數定義作為 JSON 物件，格式如下 (字數範例)：
funcDefinition = { "status": { "returnCode": 0, "errorMessage": "" }, "funcDescription": { "outputs": [ {"name": "word_count", "dataType": "integer"} ], "parameters": [ {"name": "textColumn", "displayName": "Text Column", "description": "Choose column to count words", "required": True, "value": {"type": "column"}} ], "bucketName": "bucket-OCI-FAAS", "isOutputJoinableWithInput": True } }要求中的 funcMode 為 'describeFunction' 時，在 func.py 中加入下列程式碼以傳回 funcDefinition。
def handler(ctx, data: io.BytesIO = None): response_data = "" try: body = json.loads(data.getvalue()) funcMode = body.get("funcMode") if funcMode == 'describeFunction': response_data = json.dumps(funcDefinition) except (Exception, ValueError) as ex: response_data = json.dumps( {"error": "{0}".format(str(ex))}) return response.Response( ctx, response_data, headers={"Content-Type": "application/json"} )funcMode = executeFunction - funcMode 為 'executeFunction' 時，應執行實際函數邏輯並將含有輸出的回應傳回 Oracle Analytics。從 Oracle Analytics 的資料流程呼叫已註冊的函數時，要求物件會是下列格式，其中的引數包含資料欄名稱、輸入 (bucketName、fileName、fileExtension、fileName、method 和 rowID) 及輸出 (bucketName、fileName 和 fileExtension)。
{ "args": { "textColumn": "REVIEW" }, "funcMode": "executeFunction", "input": { "bucketName": "bucket-OCI-FAAS", "fileExtension": ".csv", "fileName": "oac-fn-e99cd4fddb3844be89c7af6ea4bbeb76-input", "method": "csv", "rowID": "row_id" }, "output": { "bucketName": "bucket-OCI-FAAS", "fileExtension": ".csv", "fileName": "oac-fn-e99cd4fddb3844be89c7af6ea4bbeb76-output" } }
關於在 OCI 中建立函數
您可以透過 OCI 主控台、命令行 (Fn 專案 CLI) 或 API 來建立函數。例如，在 OCI 主控台中，依序按一下開發人員服務和函數，依照畫面中的指示建立應用程式和一或多個函數。如需詳細資訊，請參閱 Creating Functions in OCI Documentation。如果您是第一次建立函數，請依照端對端範例 Creating, Deploying, and Invoking a Helloworld Function 中的步驟進行。任何要在 Oracle Analytics 中使用的函數都必須包含任意形式標記 oac-compatible=true (請參閱上述的關於在 Oracle Analytics 設定使用 OCI Functions)。
在 OCI 主控台建立函數時的一些秘訣
- 啟用日誌 - 預設會停用函數的日誌。若要啟用函數的日誌，請按一下應用程式頁面上的日誌，然後啟用於日誌名稱提供的日誌。在資源底下，您現在可以選取瀏覽日誌並展開日誌項目，以進行除錯和診斷函數問題。
- 包含相依性 - 在函數的 requirements.txt 檔案中包含相依套裝程式。
- 遵循縮排規則 - 為 Python 函數進行編碼時，請遵循 Python 縮排規則。
- 使用函數回應錯誤 - 使用「資料流程」頁面上列出的錯誤詳細資訊來診斷問題。
- 先在本機測試函數 - 在 OCI 中建立函數之前，請先在開發環境中對函數進行本機測試，確保函數的語法和邏輯正確。
- 在 OCI 中測試函數 - 將函數與 Oracle Analytics 整合之前，請先確定可在 OCI 中以獨立函數的形式順利進行部署及呼叫。
- 增加逾時 - 依照預設，函數的逾時設定為 30 秒。如有需要，請在 OCI 主控台的編輯函數頁面中增加逾時的設定值 (例如，將逾時設定變更為 300 秒)。
- 增加記憶體 - 依照預設，函數的記憶體限制為 1024 MB。如有需要，請在 OCI 主控台的編輯函數頁面中增加記憶體限制。
- 空間最佳化 - 使用完後立即刪除不使用的檔案。
- 留意網路延遲 - 請注意，網路延遲可能會導致整體處理速度些微延遲。
整合 OCI Functions 與 Oracle Analytics 所需的原則
若要整合 Oracle Analytics 與 OCI Functions，請確保您有必要的安全原則。
您在 Oracle Analytics Cloud 與 OCI 租用戶之間的連線指定的 OCI 使用者，對於包含您要使用之 OCI 資源的區間，必須具備讀取、寫入和刪除許可權。確定 OCI 使用者屬於具備以下最低 OCI 安全原則的使用者群組。當您從 Oracle Analytics 連線 OCI 租用戶時，可以使用 OCI API 金鑰或資源主體。
注意：對於資源主體，若要包含區間下的所有 Analytics 執行處理，請指定 {request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'}，而不是 {request.principal.id='<analytics_instance_ocid>'}。
表格 32-1 OCI Functions 整合所需的安全原則
| API 金鑰原則 | 資源主體原則 |
|---|---|
Allow group <group_name> to use functions-family in compartment <compartment_name> |
Allow any-user to use functions-family in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>'} |
Allow group <group_name> to read buckets in compartment <compartment_name> |
Allow any-user to read buckets in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>'} |
Allow group <group_name> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>' |
Allow any-user to manage objects in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>', target.bucket.name='<staging_bucket_name>'} |
Allow group <group_name> to read objectstorage-namespaces in tenancy |
Allow any-user to read objectstorage-namespaces in tenancy where all {request.principal.id='<analytics_instance_ocid>'} |
表格 32-2 OCI Functions - 動態群組原則
| 原則 | 描述 |
|---|---|
Allow dynamic-group <dynamic_group> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>' |
為動態群組提供暫存儲存桶的存取權。 |
<dynamic_group>.{resource.type = 'fnfunc', resource.compartment.id = '<compartment_ocid>'} 的範例相符規則
注意：<compartment_id> 是包含函數的區間 OCID。
使用 OCI Functions 轉換資料的一般工作流程
請依照下方所列的高階作業順序，使用 OCI Functions 轉換 Oracle Analytics 的資料。
| 作業 | 描述 | 其他資訊 |
|---|---|---|
|
在 OCI 中建立函數 (需要函數開發人員權限) |
在您的 OCI 租用戶建立函數，並確定函數符合為搭配 Oracle Analytics 使用而指定的先決條件。 |
|
| 指定 OCI 原則 | 請確保您擁有使用 API 金鑰或資源主體連線所需的 OCI 原則。 | 整合 OCI Functions 與 Oracle Analytics 所需的原則 |
| 將 Oracle Analytics 連線至您的 OCI 租用戶 (需要管理員或 DV 作者權限) | 在 Oracle Analytics 中，建立您的 OCI 租用戶連線。 | |
| 在 Oracle Analytics 註冊 OCI Functions (需要管理員或 DV 作者權限) | 在 Oracle Analytics 註冊 OCI Functions 以便從資料流程呼叫。 | |
| 使用 OCI Functions 轉換資料 (需要管理員或 DV 作者權限) | 建立資料流程，然後使用套用自訂命令檔步驟呼叫 OCI 函數。 |