Azure Synapse Analytics

Once you have provided the Azure Data Lake Storage Target settings, do the following:

1. In Connections, click Create connection.

2. Select the Azure Synapse Analytics target connector and then provide the following settings:

Data target

Data gateway

A 資料移動閘道 is only required if the target database is not accessible from Qlik Cloud and can only be accessed using a Private Link (for instance, if it's located in a Virtual Private Cloud). If this is the case, select the 資料移動閘道 through which you want to access the target database.

Depending on your use case, this will either be the same 資料移動閘道 deployed to move data from the data source, or a different one.

For information about 資料移動閘道 use cases, see 何時需要 資料移動閘道？ and 常見使用案例.

If the target database is directly accessible from Qlik Cloud, select None.

Connection properties

• Server: Host name to identify the location of the Azure Synapse Analytics database.

• Port: The port through which to access your Azure Synapse Analytics database. The default is 1433.

Account properties

User Name and Password: The user name and password of a user authorized to access the Azure Synapse Analytics database.

Database properties

• Database name: There are two methods you can use to specify a database:

  • Method 1 - Select from a list: This method requires the user to be created on the master database. Click Load databases and then select a database.
  • Method 2 - Manually: Select Enter database name manually and then enter the database name.

Data loading properties

The SQL Server credential can be created automatically during runtime (the default) or you can use an existing credential. Do one of the following as appropriate:

• When the Create SQL Server credential check box is selected (the default) the SQL Server credential will be created automatically during runtime. Specify your access key in the Access key field.
• To use an existing credential, clear the Create SQL Server credential check box and specify your SQL Server credential name in the Credential name field.

Name

The display name for the connection.

Prerequisites

Permissions

You need to grant both storage permissions and database permissions, as describe below.

Storage permissions

The user specified in the Azure Synapse Analytics connector must be granted the following storage permissions.

• On the ADLS Gen2 Storage container: LIST
• On the ADLS Gen2 Storage folder: READ, WRITE and DELETE
• In the Access Control (IAM) settings for the ADLS Gen2 file system, assign the “Storage Blob Data Contributor” role to Data Movement gateway (AD App ID). It may take a few minutes for the role to take effect.

Database permissions

The user specified in the Azure Synapse Analytics connector must be granted the following permissions on the database:

• 一般授權：

  • db_owner 角色

• 表格授權：

  • 選取、插入、更新和刪除
  • 大量載入
  • 建立、警告、拖放（如果任務定義要求）

Database selection

To be able to select a database (by clicking Load databases in the connector dialog), the user specified in the connector settings needs to be created on the master database.

Driver setup

A driver is only required if you are accessing the database via 資料移動閘道. In such a case, you need to install the driver on the 資料移動閘道 machine.

您可以使用驅動程式安裝公用程式 (建議) 或手動安裝 driver。只能在不太可能發生的事件 (您在使用驅動程式安裝公用程式時遇到問題) 中嘗試手動安裝。

Using the driver installation utility to install the driver

此區段描述如何安裝所需的 driver。該流程涉及執行將會自動下載、安裝並設定所需 driver 的指令碼。您也可以執行指令碼，以根據需求更新並解除安裝 driver。

準備安裝

• 確認 Python 3.6 或更高版本安裝於 Data Movement 閘道伺服器。

  Python 會預先安裝在大部分的 Linux 發行版。您可以執行下列命令，以查看哪個 Python 版本安裝在您的系統上：

  python3 --version

安裝 driver

若要下載並安裝 driver：

1. 停止 Data Movement gateway 服務：

   sudo systemctl stop repagent

2. 可自選，確認服務已停止：

   sudo systemctl status repagent

   狀態應如下所示：

   Active: inactive (dead) since <timestamp> ago

3. 在 Data Movement 閘道機器上，將工作目錄變更為：

   opt/qlik/gateway/movement/drivers/bin

4. 執行下列命令：

   語法：

   ./install sqlserver

   若無法下載 driver (由於存取限制或技術問題)，將會顯示訊息，指示您到哪裡下載 driver 以及在 Data Movement 閘道機器上的何處複製。完成後，再次執行 install sqlserver 命令。

   否則，就會顯示 driver 的 EULA。

5. 執行下列其中一個動作：

   • 重複按下 [Enter] 以緩慢瀏覽 EULA。
   • 重複按下空格鍵以快速瀏覽 EULA。
   • 按下 q 以結束授權文字並呈現 EULA 接受選項。

6. 執行下列其中一個動作：

   • 輸入「y」並按下 [Enter] 以接受 EULA 並開始安裝。
   • 輸入「n」並按下 [Enter] 以拒絕 EULA 並退出安裝。

   • 輸入「v」並按下 [Enter] 以再次檢視 EULA。

將會安裝 driver。

7. 等待安裝完成 (以「完成！」指示)，然後開始 Data Movement gateway 服務：

   sudo systemctl start repagent

8. 可自行選擇確認服務已開始：

   sudo systemctl status repagent

   狀態應如下所示：

   Active: active (running) since <timestamp> ago

更新 driver

若您想要在安裝提供的 driver 之前解除安裝先前的 driver 版本，請執行更新命令。

若要下載並更新 driver：

1. 停止 Data Movement gateway 服務：

   sudo systemctl stop repagent

2. 可自選，確認服務已停止：

   sudo systemctl status repagent

   狀態應如下所示：

   Active: inactive (dead) since <timestamp> ago

3. 在 Data Movement 閘道機器上，將工作目錄變更為：

   opt/qlik/gateway/movement/drivers/bin

4. 執行下列命令：

   語法：

   ./update sqlserver

   若無法下載 driver (由於存取限制或技術問題)，將會顯示訊息，指示您到哪裡下載 driver 以及在 Data Movement 閘道機器上的何處複製。完成後，再次執行 update sqlserver 命令。

   否則，就會顯示 driver 的 EULA。

5. 執行下列其中一個動作：

   • 重複按下 [Enter] 以緩慢瀏覽 EULA。
   • 重複按下空格鍵以快速瀏覽 EULA。
   • 按下 q 以結束授權文字並呈現 EULA 接受選項。

6. 執行下列其中一個動作：

   • 輸入「y」並按下 [Enter] 以接受 EULA 並開始安裝。
   • 輸入「n」並按下 [Enter] 以拒絕 EULA 並退出安裝。
   • 輸入「v」並按下 [Enter] 以從頭檢閱 EULA。

將會解除安裝舊版 driver，並安裝新版 driver。

7. 等待安裝完成 (以「完成！」指示)，然後開始 Data Movement gateway 服務：

   sudo systemctl start repagent

8. 可自行選擇確認服務已開始：

   sudo systemctl status repagent

   狀態應如下所示：

   Active: active (running) since <timestamp> ago

解除安裝 driver

若您想要解除安裝 driver，請執行解除安裝命令。

若要解除安裝 driver：

1. 停止設定為使用此連接器的所有任務。

2. 在 Data Movement 閘道機器上，將工作目錄變更為：

   opt/qlik/gateway/movement/drivers/bin

3. 執行下列命令：

   語法：

   ./uninstall sqlserver

   將會解除安裝 driver。

Manually installing the driver

只有在自動驅動程式安裝無法成功完成時，才能嘗試手動安裝 driver。

You need to install both an ODBC driver and a JDBC driver.

Installing the ODBC driver

安裝 資料移動閘道 後，下載 msodbcsql<version>.x86_64.rpm 驅動程式。您可以在 /opt/qlik/gateway/movement/drivers/manifests/sqlserver.yaml 的 binary-artifacts 之下找到支援版本的直接下載連結。下載完成後，將 RPM 複製到 資料移動閘道 機器。

在 Data Movement gateway 伺服器上，開啟 shell prompt 並進行以下項目：

1. 停止 Data Movement gateway 服務：

   sudo systemctl stop repagent

2. 可自選，確認服務已停止：

   sudo systemctl status repagent

狀態應如下所示：

Active: inactive (dead) since <timestamp> ago

3. 安裝驅動程式 (RPM)。

4. 變更任務目錄至 <product_dir>/bin。

5. 複製驅動程式位置至 site_arep_login.sh 檔案，如下所示：

   echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/opt/microsoft/msodbcsql<version>/lib64/" >> site_arep_login.sh

   這將新增驅動程式至「LD_LIBRARY_PATH」並更新位於以下的驅動程式位置： site_arep_login.sh 檔案。

6. 可自選，確認已複製驅動程式位置：

   cat site_arep_login.sh

7. 開始 Data Movement gateway 服務：

   sudo systemctl start repagent

8. 可自選，確認服務已開始：

   sudo systemctl status repagent

   狀態應如下所示：

   Active: active (running) since <timestamp> ago

9. Data Movement gateway 需要以下 ODBC 物件庫：msodbcsql-18.1.so.1.1

   要檢查目前安裝的物件庫版本，請發出以下指令：

   ls /opt/microsoft/msodbcsql<version>/lib64/

   若現有的物件庫有不同的版本號碼 (例如 libmsodbcsql-18.0.so.1.1)，您需要在現有物件庫和必要物件庫之間建立符號連結。

   要這麼做，請發出以下指令：

   cd /opt/microsoft/msodbcsql<version>/lib64/
   ln -s existing_library_name msodbcsql-18.1.so.1.1

   若 existing_library_name 為目前安裝物件庫的名稱 (如 libmsodbcsql-18.0.so.1.1)。

Installing the JDBC driver

1. Download the mssql-jdbc-<version>.jar file. You can find a direct download link to the supported version under binary-artifacts in /opt/qlik/gateway/movement/drivers/manifests/sqlserver.yaml. Once the download completes, copy the JAR file to the following folder on the 資料移動閘道 machine:

   /opt/qlik/gateway/movement/qcs_agents/qdi-db-commands/lib

2. Restart the 資料移動閘道 service by running the command described in 重新啟動服務

Ports

• 當Data Movement gateway在機器之外的 Azure 運作，開啟連接埠 1433 進行傳出的通訊。
• 當Data Movement gateway在 AzureVM 上運作，開啟以下連接埠進行傳出的通訊：
  • 1433
  • 11000-11999
  • 14000-14999

Limitations and considerations

When using Azure Synapse Analytics as a target, you need to take into account the following limitations and considerations:

• 具有 CHAR/VARCHAR 資料類型和非拉丁定序 (例如「Chinese_PRC_CI_AS」) 的來源欄和需要對應至 NVARCHAR。

• 空的來源欄處理：

  • 若 移動 來源二元欄 (例如 VARBINARY 或 BLOB) 有空的值，Qlik Talend Data Integration 會將 NULL 插入對應的目標欄中。

  資訊備註空的值不是 NULL，但資料長度為零。
• 不支援超過 1 MB 的記錄 移動。
• 移動 具有 4 位元組表情圖示字元的資料需要該資料類型是目標上的寬字串 (例如 NCHAR/NVARCHAR/NCLOB)。

Data types

The following table shows the Azure Synapse Analytics data types that are supported when using Qlik Cloud and the default mapping from Qlik Cloud data types.

會保留原生資料類型資訊，並顯示在資料集檢視的原生資料類型欄中。若看不見欄，您需要開啟資料集檢視的欄選擇器並選取原生資料類型欄。