Skip to content

Commit f534726

Browse files
v-ccolinv-ccolin
authored
Merge pull request #294175 from Lucky-Wang16/0120-Update_Oracle_v2
[Doc Update] Update Oracle v2 doc
2 parents 518dd81 + 251d602 commit f534726

File tree

2 files changed

+146
-28
lines changed

2 files changed

+146
-28
lines changed

‎articles/data-factory/connector-oracle.md

Lines changed: 146 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,9 @@ For a list of data stores that are supported as sources or sinks by the copy act
3232

3333
Specifically, this Oracle connector supports:
3434

35-
- The following versions of an Oracle database:
35+
- The following versions of an Oracle database for version 2.0:
36+
- Oracle Database 19c or later
37+
- The following versions of an Oracle database for version 1.0:
3638
- Oracle 19c R1 (19.1) and higher
3739
- Oracle 18c R1 (18.1) and higher
3840
- Oracle 12c R1 (12.1) and higher
@@ -84,7 +86,114 @@ The following sections provide details about properties that are used to define
8486

8587
## Linked service properties
8688

87-
The Oracle linked service supports the following properties:
89+
The Oracle connector now supports version 2.0. Refer to this [section](#upgrade-the-oracle-connector) to upgrade your Oracle connector version from version 1.0. For the property details, see the corresponding sections.
90+
91+
- [Version 2.0](#version-20)
92+
- [Version 1.0](#version-10)
93+
94+
### Version 2.0
95+
96+
The Oracle linked service supports the following properties when apply version 2.0:
97+
98+
| Property | Description | Required |
99+
|:--- |:--- |:--- |
100+
| type | The type property must be set to **Oracle**. | Yes |
101+
| version | The version that you specify. The value is `2.0`. | Yes |
102+
| server | The location of Oracle database you want to connect to. You can refer to [server property configuration](#server-property-configuration) to specify it. | Yes |
103+
| authenticationType | Authentication type for connecting to the Oracle database. Only **Basic** auth is supported now. | Yes |
104+
| username | The Oracle database username. | Yes |
105+
| password | The Oracle database password. | Yes |
106+
| connectVia | The [integration runtime](concepts-integration-runtime.md) to be used to connect to the data store. Learn more from [Prerequisites](#prerequisites) section. If not specified, the default Azure Integration Runtime is used. |No |
107+
108+
More connection properties you can set in linked service per your case:
109+
110+
| Property | Description | Required | Default value |
111+
|:--- |:--- |:--- |:--- |
112+
| encryptionClient | Specifies the encryption client behavior. Supported values are `accepted`, `rejected`, `requested`, or `required`. Type: string | No | `required` |
113+
| encryptionTypesClient | Specifies the encryption algorithms that client can use. Supported values are `AES128`, `AES192`, `AES256`, `3DES112`, `3DES168`. Type: string | No | `(AES256)` |
114+
| cryptoChecksumClient | Specifies the desired data integrity behavior when this client connects to a server. Supported values are `accepted`, `rejected`, `requested`, or `required`. Type: string | No | `required` |
115+
| cryptoChecksumTypesClient | Specifies the crypto-checksum algorithms that client can use. Supported values are `SHA1`, `SHA256`, `SHA384`, `SHA512`. Type: string | No | `(SHA512)` |
116+
| initialLobFetchSize | Specifies the amount that the source initially fetches for LOB columns. Type: int | No | 0 |
117+
| fetchSize | Specifies the number of bytes that the driver allocates to fetch the data in one database round-trip. Type: int | No | 10 MB |
118+
| statementCacheSize | Specifies the number of cursors or statements to be cached for each database connection. Type: int | No | 0 |
119+
| initializationString | Specifies a command that is issued immediately after connecting to the database to manage session settings. Type: string | No | null |
120+
| enableBulkLoad | Specifies whether to use bulk copy or batch insert when loading data into the database. Type: boolean | No | true |
121+
| supportV1DataTypes | Specifies whether to use the version 1.0 data type mappings. Do not set this to true unless you want to keep backward compatibility with version 1.0's data type mappings. Type: boolean | No, this property is for backward compatibility use only | false |
122+
| fetchTswtzAsTimestamp | Specifies whether the driver returns column value with the TIMESTAMP WITH TIME ZONE data type as DateTime or string. This setting is ignored if supportV1DataTypes is not true. Type: boolean | No, this property is for backward compatibility use only | true |
123+
124+
#### `server` property configuration
125+
126+
For `server` property, you can specify it in one of the following three formats:
127+
128+
| Format | Example |
129+
|:--- |:--- |
130+
|[Connect Descriptor](https://docs.oracle.com/en/database/oracle/oracle-database/23/netag/identifying-and-accessing-database.html#GUID-8D28E91B-CB72-4DC8-AEFC-F5D583626CF6)| (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))|
131+
|[Easy Connect (Plus) Naming](https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy-Connect-Plus.pdf)|salesserver1:1521/sales.us.example.com|
132+
|[Oracle Net Services Name (TNS Alias)](https://docs.oracle.com/en/database/oracle/oracle-database/23/netrf/local-naming-parameters-in-tns-ora-file.html#GUID-12C94B15-2CE1-4B98-9D0C-8226A9DDF4CB) (only for the self-hosted integration runtime)|sales|
133+
134+
For the parameters used in `server`, we provide an allowlist to avoid security risks, as shown below. You can refer to it to determine which parameters to be set. If the disallowed parameter is set, the connection will fail.
135+
136+
- Allowlist for using the Azure integration runtime:
137+
138+
HOST,PORT,PROTOCOL,SERVICE_NAME,SID,INSTANCE_NAME,SERVER,CONNECT_TIMEOUT,RETRY_COUNT,RETRY_DELAY,SSL_VERSION,SSL_SERVER_DN_MATCH,SSL_SERVER_CERT_DN
139+
- Allowlist for using the self-hosted integration runtime:
140+
141+
HOST,PORT,PROTOCOL,ENABLE,EXPIRE_TIME,FAILOVER,LOAD_BALANCE,RECV_BUF_SIZE,SDU,SEND_BUF_SIZE,SOURCE_ROUTE,TYPE_OF_SERVICE,COLOCATION_TAG,CONNECTION_ID_PREFIX,FAILOVER_MODE,GLOBAL_NAME,HS,INSTANCE_NAME,POOL_BOUNDARY,POOL_CONNECTION_CLASS,POOL_NAME,POOL_PURITY,RDB_DATABASE,SHARDING_KEY,SHARDING_KEY_ID,SUPER_SHARDING_KEY,SERVER,SERVICE_NAME,SID,TUNNEL_SERVICE_NAME,SSL_CLIENT_AUTHENTICATION,SSL_CERTIFICATE_ALIAS,SSL_CERTIFICATE_THUMBPRINT,SSL_VERSION,SSL_SERVER_DN_MATCH,SSL_SERVER_CERT_DN,WALLET_LOCATION,CONNECT_TIMEOUT,RETRY_COUNT,RETRY_DELAY,TRANSPORT_CONNECT_TIMEOUT,RECV_TIMEOUT,COMPRESSION,COMPRESSION_LEVELS
142+
143+
**Example:**
144+
145+
```json
146+
{
147+
"name": "OracleLinkedService",
148+
"properties": {
149+
"type": "Oracle",
150+
"version": "2.0",
151+
"typeProperties": {
152+
"server": "<server name>",
153+
"username": "<user name>",
154+
"password": "<password>",
155+
"authenticationType": "<authentication type>"
156+
},
157+
"connectVia": {
158+
"referenceName": "<name of Integration Runtime>",
159+
"type": "IntegrationRuntimeReference"
160+
}
161+
}
162+
}
163+
```
164+
165+
**Example: store password in Azure Key Vault**
166+
167+
```json
168+
{
169+
"name": "OracleLinkedService",
170+
"properties": {
171+
"type": "Oracle",
172+
"version": "2.0",
173+
"typeProperties": {
174+
"server": "<server name>",
175+
"username": "<user name>",
176+
"authenticationType": "<authentication type>",
177+
"password": { 
178+
"type": "AzureKeyVaultSecret", 
179+
"store": { 
180+
"referenceName": "<Azure Key Vault linked service name>", 
181+
"type": "LinkedServiceReference" 
182+
}, 
183+
"secretName": "<secretName>" 
184+
}
185+
},
186+
"connectVia": {
187+
"referenceName": "<name of Integration Runtime>",
188+
"type": "IntegrationRuntimeReference"
189+
}
190+
}
191+
}
192+
```
193+
194+
### Version 1.0
195+
196+
The Oracle linked service supports the following properties when apply version 1.0:
88197

89198
| Property | Description | Required |
90199
|:--- |:--- |:--- |
@@ -237,7 +346,7 @@ To copy data from Oracle, set the source type in the copy activity to `OracleSou
237346
|:--- |:--- |:--- |
238347
| type | The type property of the copy activity source must be set to `OracleSource`. | Yes |
239348
| oracleReaderQuery | Use the custom SQL query to read data. An example is `"SELECT * FROM MyTable"`.<br>When you enable partitioned load, you need to hook any corresponding built-in partition parameters in your query. For examples, see the [Parallel copy from Oracle](#parallel-copy-from-oracle) section. | No |
240-
| convertDecimalToInteger | Oracle NUMBER type with zero or unspecified scale will be converted to corresponding integer. Allowed values are **true** and **false** (default).| No |
349+
| convertDecimalToInteger | Oracle NUMBER type with zero or unspecified scale will be converted to corresponding integer. Allowed values are **true** and **false** (default). <br>If you are using Oracle version 2.0, this property will only be allowed to be set when supportV1DataTypes is true. | No |
241350
| partitionOptions | Specifies the data partitioning options used to load data from Oracle. <br>Allowed values are: **None** (default), **PhysicalPartitionsOfTable**, and **DynamicRange**.<br>When a partition option is enabled (that is, not `None`), the degree of parallelism to concurrently load data from an Oracle database is controlled by the [`parallelCopies`](copy-activity-performance-features.md#parallel-copy) setting on the copy activity. | No |
242351
| partitionSettings | Specify the group of the settings for data partitioning. <br>Apply when the partition option isn't `None`. | No |
243352
| partitionNames | The list of physical partitions that needs to be copied. <br>Apply when the partition option is `PhysicalPartitionsOfTable`. If you use a query to retrieve the source data, hook `?AdfTabularPartitionName` in the WHERE clause. For an example, see the [Parallel copy from Oracle](#parallel-copy-from-oracle) section. | No |
@@ -376,37 +485,46 @@ You are suggested to enable parallel copy with data partitioning especially when
376485

377486
When you copy data from and to Oracle, the following interim data type mappings are used within the service. To learn about how the copy activity maps the source schema and data type to the sink, see [Schema and data type mappings](copy-activity-schema-and-type-mapping.md).
378487

379-
| Oracle data type | Interim data type |
380-
|:--- |:--- |
381-
| BFILE |Byte[] |
382-
| BLOB |Byte[]<br/>(only supported on Oracle 10g and higher) |
383-
| CHAR |String |
384-
| CLOB |String |
385-
| DATE |DateTime |
386-
| FLOAT |Decimal, String (if precision > 28) |
387-
| INTEGER |Decimal, String (if precision > 28) |
388-
| LONG |String |
389-
| LONG RAW |Byte[] |
390-
| NCHAR |String |
391-
| NCLOB |String |
392-
| NUMBER (p,s) |Decimal, String (if p > 28) |
393-
| NUMBER without precision and scale |Double |
394-
| NVARCHAR2 |String |
395-
| RAW |Byte[] |
396-
| ROWID |String |
397-
| TIMESTAMP |DateTime |
398-
| TIMESTAMP WITH LOCAL TIME ZONE |String |
399-
| TIMESTAMP WITH TIME ZONE |String |
400-
| UNSIGNED INTEGER |Number |
401-
| VARCHAR2 |String |
402-
| XML |String |
488+
| Oracle data type | Interim service data type (for version 2.0) | Interim service data type (for version 1.0) |
489+
|:--- |:--- |:--- |
490+
| BFILE |Byte[] | Byte[] |
491+
| BINARY_FLOAT | Single | Single |
492+
| BINARY_DOUBLE | Double | Double |
493+
| BLOB |Byte[] | Byte[] |
494+
| CHAR |String |String |
495+
| CLOB |String |String |
496+
| DATE |DateTime |DateTime |
497+
| FLOAT (P < 16) | Double | Double |
498+
| FLOAT (P >= 16) | Decimal | Double |
499+
| INTERVAL YEAR TO MONTH |Int64 |String |
500+
| INTERVAL DAY TO SECOND |TimeSpan |String |
501+
| LONG |String |String |
502+
| LONG RAW |Byte[] |Byte[] |
503+
| NCHAR |String |String |
504+
| NCLOB |String |String |
505+
| NUMBER (p,s) |Int16, Int32, Int64, Double, Single, Decimal |Decimal, String (if p > 28) |
506+
| NUMBER without precision and scale | Decimal |Double |
507+
| NVARCHAR2 |String |String |
508+
| RAW |Byte[] |Byte[] |
509+
| TIMESTAMP |DateTime |DateTime |
510+
| TIMESTAMP WITH LOCAL TIME ZONE |DateTime |DateTime |
511+
| TIMESTAMP WITH TIME ZONE |DateTimeOffset |DateTime |
512+
| VARCHAR2 |String |String |
513+
| XMLTYPE |String |String |
403514

404515
> [!NOTE]
405-
> The data types INTERVAL YEAR TO MONTH and INTERVAL DAY TO SECOND aren't supported.
516+
> NUMBER(p,s) is mapped to the appropriate interim service data type depending on the precision (p) and scale (s).
406517
407518
## Lookup activity properties
408519

409520
To learn details about the properties, check [Lookup activity](control-flow-lookup-activity.md).
410521

522+
## Upgrade the Oracle connector
523+
524+
Here are steps that help you upgrade the Oracle connector:
525+
526+
1. In **Edit linked service** page, select **2.0 (Preview)** under **Version** and configure the linked service by referring to [Linked service properties version 2.0](#version-20).
527+
1. The data type mapping for the Oracle linked service version 2.0 is different from that for the version 1.0. To learn the latest data type mapping, see [Data type mapping for Oracle](#data-type-mapping-for-oracle).
528+
411529
## Related content
412530
For a list of data stores supported as sources and sinks by the copy activity, see [Supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

‎articles/data-factory/media/connector-oracle/configure-oracle-linked-service.png

-2.32 KB
Loading

0 commit comments

Comments
 (0)