Doc: update documents

aliyun · Dec 20, 2024 · 3f0fb8d · 3f0fb8d
1 parent 90a155b
commit 3f0fb8d
Show file tree

Hide file tree

Showing 5 changed files with 68 additions and 8 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,20 @@
 # Changelog
+
+## [0.51.2-public] - 2024-12-20
+### Features
+- **Authorization** Introduced the `credential-java` authorization package, now supporting authentication with `AlibabaCloudCredentialsProvider`.
+- **StreamUploadSession** Added awareness for Slot updates and automatic retry logic.
+- **table-api** Introduced the `TableRetryHandler` class, adding retry logic to the `table-api`.
+- **udf** The `InputSplitter` now includes the method `setLimit`.
+
+### Changes
+- **TypeInfo** The `StructTypeInfo` class now includes the method `getTypeName(boolean quote)`. In version `0.51.0-public (rc0)`, `StructTypeInfo` defaulted to quoting field names with backticks. We suspect that this change may affect users, so we decided to revert to the original behavior (not quoting by default). Users can now call `getTypeName(true)` when quoting is needed.
+
+### Fixes
+- **TypeInfo** Field names will now be correctly escaped when quoted with backticks.
+- **MCQA2** Fixed an issue where the `getRawTaskResults` interface call in MCQA2 jobs could not retrieve results.
+
+
 ## [0.51.0-public] - 2024-12-05
 ### Features
 - **MapReduce** Supports multi pipeline output.
@@ -63,7 +79,7 @@
 - **SQLExecutor** MCQA 2.0 job supports retrieving InstanceProgress information
 
 ### Changes
-- **Quote** added backticks for quoting names in Struct type TypeInfo and other methods that assemble SQL
+- **TypeInfo** added backticks for quoting names in Struct type TypeInfo and other methods that assemble SQL
 - **AutoClosable** to remind users to properly close resources, added corresponding `close()` methods to the following resource classes to prompt users to close resources correctly:
   - `UpsertStream` in the `odps-sdk-core` package,
   - `LocalOutputStreamSet`, `ReduceDriver.ReduceContextImpl`, `MapDriver.DirectMapContextImpl`, `LocalRecordWriter` in the `odps-sdk-impl` package

diff --git a/CHANGELOG_CN.md b/CHANGELOG_CN.md
@@ -1,4 +1,21 @@
 # 更新日志
+
+## [0.51.2-public] - 2024-12-20
+### 功能
+- **Authorization** 引入`credential-java`鉴权包，现在能够使用`AlibabaCloudCredentialsProvider`进行鉴权
+- **StreamUploadSession** 新增对 Slot 更新的感知和自动重试逻辑
+- **table-api** 引入`TableRetryHandler`类，为`table-api`添加重试逻辑
+- **udf** 中`InputSplitter`新增方法 `setLimit`
+
+### 变更
+- **TypeInfo** `StructTypeInfo` 新增方法 `getTypeName(boolean quote)`，在 `0.51.0-public (rc0)` 版本，`StructTypeInfo` 默认会对字段名使用反引号进行 quote，我们怀疑这项变更对用户有影响，因此决定恢复原行为（默认不进行quote）
+而是当用户需要 quote 时，可以调用 `getTypeName(true)`
+
+### 修复
+- **TypeInfo** 当对字段使用反引号进行 quote 时，现在会正确对字段名进行转义
+- **MCQA2** 修复了 MCQA2 作业调用 `getRawTaskResults` 接口取不到结果的问题
+
+
 ## [0.51.0-public] - 2024-12-05
 
 ### 功能
@@ -58,7 +75,7 @@
 - **SQLExecutor** MCQA 2.0 作业支持获取 InstanceProgress 信息
 
 ### 变更
-- **Quote** 对 Struct 类型的 TypeInfo，和其他拼装 SQL 的方法，使用反引号对名字进行 quote
+- **TypeInfo** 对 Struct 类型的 TypeInfo，和其他拼装 SQL 的方法，使用反引号对名字进行 quote
 - **AutoClosable** 为了提醒用户正确关闭资源，对下列资源类，增加了相应的 `close()` 方法，以提醒用户正确关闭资源。
   - `odps-sdk-core` 包下的 `UpsertStream`，
   - `odps-sdk-impl` 包下的 `LocalOutputStreamSet`，`ReduceDriver.ReduceContextImpl`，`MapDriver.DirectMapContextImpl`，`LocalRecordWriter`

diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md
@@ -4,6 +4,21 @@ sidebar_position: 6
 ---
 
 # 更新日志
+## [0.51.2-public] - 2024-12-20
+### 功能
+- **Authorization** 引入`credential-java`鉴权包，现在能够使用`AlibabaCloudCredentialsProvider`进行鉴权
+- **StreamUploadSession** 新增对 Slot 更新的感知和自动重试逻辑
+- **table-api** 引入`TableRetryHandler`类，为`table-api`添加重试逻辑
+- **udf** 中`InputSplitter`新增方法 `setLimit`
+
+### 变更
+- **TypeInfo** `StructTypeInfo` 新增方法 `getTypeName(boolean quote)`，在 `0.51.0-public (rc0)` 版本，`StructTypeInfo` 默认会对字段名使用反引号进行 quote，我们怀疑这项变更对用户有影响，因此决定恢复原行为（默认不进行quote）
+  而是当用户需要 quote 时，可以调用 `getTypeName(true)`
+
+### 修复
+- **TypeInfo** 当对字段使用反引号进行 quote 时，现在会正确对字段名进行转义
+- **MCQA2** 修复了 MCQA2 作业调用 `getRawTaskResults` 接口取不到结果的问题
+
 ## [0.51.0-public] - 2024-12-05
 
 ### 功能
@@ -63,7 +78,7 @@ sidebar_position: 6
 - **SQLExecutor** MCQA 2.0 作业支持获取 InstanceProgress 信息
 
 ### 变更
-- **Quote** 对 Struct 类型的 TypeInfo，和其他拼装 SQL 的方法，使用反引号对名字进行 quote
+- **TypeInfo** 对 Struct 类型的 TypeInfo，和其他拼装 SQL 的方法，使用反引号对名字进行 quote
 - **AutoClosable** 为了提醒用户正确关闭资源，对下列资源类，增加了相应的 `close()` 方法，以提醒用户正确关闭资源。
   - `odps-sdk-core` 包下的 `UpsertStream`，
   - `odps-sdk-impl` 包下的 `LocalOutputStreamSet`，`ReduceDriver.ReduceContextImpl`，`MapDriver.DirectMapContextImpl`，`LocalRecordWriter`

diff --git a/docs/docs/core-concept/init-odps-client.md b/docs/docs/core-concept/init-odps-client.md
@@ -51,10 +51,20 @@ public static Odps buildWithStsToken(String accessId, String accessKey, String s
 
 ## 使用阿里云CredentialProvider构建客户端
 
-此方法适用于如ECS实例上的RAM角色授权等场景。
+此方法适用于如使用默认凭据链，或ECS实例上的RAM角色授权等场景。
 
 ### 示例代码
+使用 [credential-java](https://github.com/aliyun/credentials-java) 包
+```java
+public static Odps buildWithCredentialProvider(AlibabaCloudCredentialsProvider credentialProvider) {
+  Account account = new AklessAccount(credentialProvider);
+  Odps odps = new Odps(account);
+  odps.setEndpoint(SAMPLE_ENDPOINT);
+  return odps;
+}
+```
 
+使用 aliyun-java-auth 包
 ```java
 public static Odps buildWithCredentialProvider(ICredentialProvider credentialProvider) {
   Account account = new AklessAccount(credentialProvider);
@@ -65,8 +75,10 @@ public static Odps buildWithCredentialProvider(ICredentialProvider credentialPro
 ```
 
 ### 说明
-
-CredentialProvider 是阿里云提供的一种无AK认证方式，它实际上提供了一种基于STS Token的生成和自动轮换机制。阿里云的`aliyun-java-auth`包提供了多种`ICredentialProvider`的实现，例如`DefaultCredentialProvider`和`RamRoleArnCredentialProvider`，用户可以根据需要选择不同的实现。
+CredentialProvider 是阿里云提供的一种无AK认证方式，它实际上提供了一种基于STS Token的生成和自动轮换机制。
+阿里云的`credential-java`包提供了`AlibabaCloudCredentialsProvider`接口和多种实现，
+阿里云的`aliyun-java-auth`包提供了`ICredentialProvider`接口和多种实现，
+用户可以根据需要选择不同的实现。
 
 ## 使用双重签名认证构建客户端
 
@@ -115,5 +127,5 @@ String bearerToken = sm.generateAuthorizationToken(policy, "BEARER");
 - [阿里云MaxCompute官方文档](https://help.aliyun.com/zh/maxcompute)
 - [阿里云RAM用户指南](https://help.aliyun.com/zh/maxcompute/getting-started/prepare-a-ram-user)
 - [Policy 权限控制文档](https://help.aliyun.com/zh/maxcompute/user-guide/policy-based-access-control-1)
-- [阿里云 CredentialProvider 使用文档](https://help.aliyun.com/zh/sdk/developer-reference/v2-java-integrated-sdk)
+- [阿里云 CredentialProvider 使用文档](https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-access-credentials)
 
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
@@ -16,7 +16,7 @@ MaxCompute的Java SDK为开发者提供了丰富的Java编程语言接口，允
 <dependency>
     <groupId>com.aliyun.odps</groupId>
     <artifactId>odps-sdk-core</artifactId>
-    <version>0.51.0-public</version>
+    <version>0.51.2-public</version>
 </dependency>
 ```
 请确保您使用的是[Maven Central Repository](https://mvnrepository.com/artifact/com.aliyun.odps/odps-sdk-core)或[阿里云Maven仓库](https://developer.aliyun.com/mvn/)中可用的最新稳定版本。