From aaf278b864e96a463a1dde5e76d6221da7cdc4a8 Mon Sep 17 00:00:00 2001 From: Wen Jiazhi Date: Mon, 27 Nov 2023 16:06:43 +0800 Subject: [PATCH 1/3] dataservice: update batch endpoint request body format --- tidb-cloud/data-service-manage-endpoint.md | 47 +++++++++++++------ .../data-service-postman-integration.md | 2 +- 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/tidb-cloud/data-service-manage-endpoint.md b/tidb-cloud/data-service-manage-endpoint.md index de386127d32e3..4f92131823428 100644 --- a/tidb-cloud/data-service-manage-endpoint.md +++ b/tidb-cloud/data-service-manage-endpoint.md @@ -117,8 +117,17 @@ On the right pane of the endpoint details page, you can click the **Properties** > - The `page_size` must be less than or equal to the **Max Rows** property. Otherwise, an error is returned. - **Cache Response**: this property is available only when the request method is `GET`. When **Cache Response** is enabled, TiDB Cloud Data Service can cache the response returned by your `GET` requests within a specified time-to-live (TTL) period. +<<<<<<< Updated upstream - **Time-to-live (s)**: this property is available only when **Cache Response** is enabled. You can use it to specify the time-to-live (TTL) period in seconds for cached response. During the TTL period, if you make the same `GET` requests again, Data Service returns the cached response directly instead of fetching data from the target database again, which improves your query performance. - **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by adding an array of data objects in the `--data-raw` option of your curl command when calling the endpoint. +======= +- **Time-to-live(s)**: this property is available only when **Cache Response** is enabled. You can use it to specify the time-to-live (TTL) period in seconds for cached response. During the TTL period, if you make the same `GET` requests again, Data Service returns the cached response directly instead of fetching data from the target database again, which improves your query performance. +- **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by putting an array of data objects to the `items` field of an object in the `--data-raw` option of your curl command when calling the endpoint. + + > **Note:** + > + > The endpoint with **Batch Operation** enabled supports both array and object formats for the request body: `[{dataObject1}, {dataObject2}]` and `{items: [{dataObject1}, {dataObject2}]}`. For better compatibility with other systems, it is recommended that you use the object format `{items: [{dataObject1}, {dataObject2}]}`. +>>>>>>> Stashed changes ### Write SQL statements @@ -283,13 +292,17 @@ TiDB Cloud Data Service generates code examples to help you call an endpoint. To ```bash curl --digest --user ':' \ - --request POST 'https://.data.tidbcloud.com/api/v1beta/app//endpoint/' \ - --header 'content-type: application/json'\ - --header 'endpoint-type: draft' - --data-raw '[{ - "age": "${age}", - "career": "${career}" - }]' + --request POST 'https://.data.tidbcloud.com/api/v1beta/app//endpoint/' \ + --header 'content-type: application/json'\ + --header 'endpoint-type: draft' + --data-raw '{ + "items": [ + { + "age": "${age}", + "career": "${career}" + } + ] + }' ``` @@ -302,12 +315,16 @@ TiDB Cloud Data Service generates code examples to help you call an endpoint. To ```bash curl --digest --user ':' \ - --request POST 'https://.data.tidbcloud.com/api/v1beta/app//endpoint/' - --header 'content-type: application/json'\ - --data-raw '[{ - "age": "${age}", - "career": "${career}" - }]' + --request POST 'https://.data.tidbcloud.com/api/v1beta/app//endpoint/' \ + --header 'content-type: application/json'\ + --data-raw '{ + "items": [ + { + "age": "${age}", + "career": "${career}" + } + ] + }' ``` @@ -324,7 +341,7 @@ TiDB Cloud Data Service generates code examples to help you call an endpoint. To - If the request method of your endpoint is `GET` and **Pagination** is enabled for the endpoint, you can paginate the results by updating the values of `page=` and `page_size=` with your desired values. For example, to get the second page with 10 items per page, use `page=2` and `page_size=10`. - If the request method of your endpoint is `POST` or `PUT`, fill in the `--data-raw` option according to the rows of data that you want to operate on. - - For endpoints with **Batch Operation** enabled, the `--data-raw` option accepts an array of data objects so you can operate on multiple rows of data using one endpoint. + - For endpoints with **Batch Operation** enabled, the `--data-raw` option accepts an object with an `items` field containing an array of data objects so you can operate on multiple rows of data using one endpoint. - For endpoints with **Batch Operation** not enabled, the `--data-raw` option only accepts one data object. - If the endpoint contains parameters, specify the parameter values when calling the endpoint. @@ -357,4 +374,4 @@ To delete an endpoint, perform the following steps: 1. Navigate to the [**Data Service**](https://tidbcloud.com/console/data-service) page of your project. 2. In the left pane, click the name of your target Data App to view its endpoints. 3. Click the name of the endpoint you want to delete, and then click **...** > **Delete** in the upper-right corner. -4. Click **Delete** to confirm the deletion. \ No newline at end of file +4. Click **Delete** to confirm the deletion. diff --git a/tidb-cloud/data-service-postman-integration.md b/tidb-cloud/data-service-postman-integration.md index 89545832c2d26..4be7d94d8b3bf 100644 --- a/tidb-cloud/data-service-postman-integration.md +++ b/tidb-cloud/data-service-postman-integration.md @@ -72,7 +72,7 @@ To run your Data App in Postman, take the following steps: - For an endpoint with parameters, you need to fill in the parameter values first, and then click **Send**. - For a `GET` or `DELETE` request, fill in the parameter values in the **Query Params** table. - - For a `POST` or `PUT` request, click the **Body** tab, and then fill in the parameter values as a JSON object. If **Batch Operation** is enabled for the endpoint in TiDB Cloud Data Service, fill in the parameter values as an array of JSON objects. + - For a `POST` or `PUT` request, click the **Body** tab, and then fill in the parameter values as a JSON object. If **Batch Operation** is enabled for the endpoint in TiDB Cloud Data Service, fill in the parameter values to the `items` field as an array of JSON objects. 3. Check the response in the lower pane. From 6b6863b2862530f32a5c8d1c2f12e440e2882d2b Mon Sep 17 00:00:00 2001 From: Wen Jiazhi Date: Mon, 27 Nov 2023 16:09:30 +0800 Subject: [PATCH 2/3] resolve conflict --- tidb-cloud/data-service-manage-endpoint.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/tidb-cloud/data-service-manage-endpoint.md b/tidb-cloud/data-service-manage-endpoint.md index 4f92131823428..aff327aa6a1ef 100644 --- a/tidb-cloud/data-service-manage-endpoint.md +++ b/tidb-cloud/data-service-manage-endpoint.md @@ -117,17 +117,12 @@ On the right pane of the endpoint details page, you can click the **Properties** > - The `page_size` must be less than or equal to the **Max Rows** property. Otherwise, an error is returned. - **Cache Response**: this property is available only when the request method is `GET`. When **Cache Response** is enabled, TiDB Cloud Data Service can cache the response returned by your `GET` requests within a specified time-to-live (TTL) period. -<<<<<<< Updated upstream -- **Time-to-live (s)**: this property is available only when **Cache Response** is enabled. You can use it to specify the time-to-live (TTL) period in seconds for cached response. During the TTL period, if you make the same `GET` requests again, Data Service returns the cached response directly instead of fetching data from the target database again, which improves your query performance. -- **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by adding an array of data objects in the `--data-raw` option of your curl command when calling the endpoint. -======= - **Time-to-live(s)**: this property is available only when **Cache Response** is enabled. You can use it to specify the time-to-live (TTL) period in seconds for cached response. During the TTL period, if you make the same `GET` requests again, Data Service returns the cached response directly instead of fetching data from the target database again, which improves your query performance. - **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by putting an array of data objects to the `items` field of an object in the `--data-raw` option of your curl command when calling the endpoint. > **Note:** > > The endpoint with **Batch Operation** enabled supports both array and object formats for the request body: `[{dataObject1}, {dataObject2}]` and `{items: [{dataObject1}, {dataObject2}]}`. For better compatibility with other systems, it is recommended that you use the object format `{items: [{dataObject1}, {dataObject2}]}`. ->>>>>>> Stashed changes ### Write SQL statements From 543dc1f82b94437f7ebbc7d506b9458142b79387 Mon Sep 17 00:00:00 2001 From: clark1013 Date: Mon, 27 Nov 2023 16:19:15 +0800 Subject: [PATCH 3/3] Update tidb-cloud/data-service-manage-endpoint.md Co-authored-by: Grace Cai --- tidb-cloud/data-service-manage-endpoint.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/data-service-manage-endpoint.md b/tidb-cloud/data-service-manage-endpoint.md index aff327aa6a1ef..39581e6b1a268 100644 --- a/tidb-cloud/data-service-manage-endpoint.md +++ b/tidb-cloud/data-service-manage-endpoint.md @@ -118,7 +118,7 @@ On the right pane of the endpoint details page, you can click the **Properties** - **Cache Response**: this property is available only when the request method is `GET`. When **Cache Response** is enabled, TiDB Cloud Data Service can cache the response returned by your `GET` requests within a specified time-to-live (TTL) period. - **Time-to-live(s)**: this property is available only when **Cache Response** is enabled. You can use it to specify the time-to-live (TTL) period in seconds for cached response. During the TTL period, if you make the same `GET` requests again, Data Service returns the cached response directly instead of fetching data from the target database again, which improves your query performance. -- **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by putting an array of data objects to the `items` field of an object in the `--data-raw` option of your curl command when calling the endpoint. +- **Batch Operation**: this property is visible only when the request method is `POST` or `PUT`. When **Batch Operation** is enabled, you can operate on multiple rows in a single request. For example, you can insert multiple rows of data in a single `POST` request by putting an array of data objects to the `items` field of an object in the `--data-raw` option of your curl command when [calling the endpoint](#call-an-endpoint). > **Note:** >