update documents and changelog (#651)

CHANGELOG.md

@@ -1,9 +1,11 @@
 ## v2.0.1
+BREAKING CHANGES:
+- `azapi_resource`, `azapi_update_resource` resources and data sources' `output` field defaults to the readonly fields when the `response_export_values` is not specified.
+- `azapi_resource_list` data source's `output` field defaults to the response when the `response_export_values` is not specified.
+
 ENHANCEMENTS:
 - `azapi_data_plane_resource` resource: Support `Microsoft.Purview/accounts/Scanning/managedvirtualnetworks` type.
 - Support a default retry policy that retries when GET request fails with 404 status code after resource creation.
-- `azapi_resource`, `azapi_update_resource` resources and data sources' `output` field defaults to the readonly fields when the `response_export_values` is not specified.
-- `azapi_resource_list` data source's `output` field defaults to the response when the `response_export_values` is not specified.
 - `azapi` provider: Support `disable_default_output` field, which is used to disable the default output for the resources and data sources.
 - Update bicep types to https://github.com/ms-henglu/bicep-types-az/commit/c3ff45dfffe7f229447639b5982a1e2deadc1b71
 

docs/data-sources/resource_list.md

@@ -23,15 +23,20 @@ provider "azapi" {
 }
 
 data "azapi_resource_list" "listBySubscription" {
-  type                   = "Microsoft.Automation/automationAccounts@2021-06-22"
-  parent_id              = "/subscriptions/00000000-0000-0000-0000-000000000000"
-  response_export_values = ["*"]
+  type      = "Microsoft.Automation/automationAccounts@2021-06-22"
+  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000"
+  response_export_values = {
+    "values" = "value[].{name: name, publicNetworkAccess: properties.publicNetworkAccess}"
+    "names"  = "value[].name"
+  }
 }
 
 data "azapi_resource_list" "listByResourceGroup" {
-  type                   = "Microsoft.Automation/automationAccounts@2021-06-22"
-  parent_id              = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1"
-  response_export_values = ["*"]
+  type      = "Microsoft.Automation/automationAccounts@2021-06-22"
+  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1"
+  response_export_values = {
+    "names" = "value[].name"
+  }
 }
 
 data "azapi_resource_list" "listSubnetsByVnet" {
@@ -65,27 +70,46 @@ data "azapi_resource_list" "listSubnetsByVnet" {
 - `query_parameters` (Map of List of String) A map of query parameters to include in the request
 - `response_export_values` (Dynamic) The attribute can accept either a list or a map.
 
-- **List**: A list of paths that need to be exported from the response body. Setting it to `["*"]` will export the full response body. Here's an example. If it sets to `["properties.loginServer", "properties.policies.quarantinePolicy.status"]`, it will set the following HCL object to the computed property output.
+- **List**: A list of paths that need to be exported from the response body. Setting it to `["*"]` will export the full response body. Here's an example. If it sets to `["value"]`, it will set the following HCL object to the computed property output.
 
 	```text
 	{
-		properties = {
-			loginServer = "registry1.azurecr.io"
-			policies = {
-				quarantinePolicy = {
-					status = "disabled"
-				}
-			}
+	  "value" = [
+		{
+		  "id" = "/subscriptions/000000/resourceGroups/demo-rg/providers/Microsoft.Automation/automationAccounts/example"
+		  "location" = "eastus2"
+		  "name" = "example"
+		  "properties" = {
+			"creationTime" = "2024-10-11T08:18:38.737+00:00"
+			"disableLocalAuth" = false
+			"lastModifiedTime" = "2024-10-11T08:18:38.737+00:00"
+			"publicNetworkAccess" = true
+		  }
+		  "tags" = {}
+		  "type" = "Microsoft.Automation/AutomationAccounts"
 		}
+	  ]
 	}
 	```
 
-- **Map**: A map where the key is the name for the result and the value is a JMESPath query string to filter the response. Here's an example. If it sets to `{"login_server": "properties.loginServer", "quarantine_status": "properties.policies.quarantinePolicy.status"}`, it will set the following HCL object to the computed property output.
+- **Map**: A map where the key is the name for the result and the value is a JMESPath query string to filter the response. Here's an example. If it sets to `{"values": "value[].{name: name, publicNetworkAccess: properties.publicNetworkAccess}", "names": "value[].name"}`, it will set the following HCL object to the computed property output.
 
 	```text
 	{
-		"login_server" = "registry1.azurecr.io"
-		"quarantine_status" = "disabled"
+		"names" = [
+			"example",
+			"fredaccount01",
+		]
+		"values" = [
+			{
+			  "name" = "example"
+			  "publicNetworkAccess" = true
+			},
+			{
+			  "name" = "fredaccount01"
+			  "publicNetworkAccess" = null
+			},
+		]
 	}
 	```
 

docs/guides/2.0-upgrade-guide.md

@@ -497,3 +497,16 @@ When you run `terraform plan`, you will see the following error message:
 
   How to fix:  
   Please set it to `true` explicitly if you want to authenticate using Managed Service Identity.
+
+- `azapi_resource`, `azapi_update_resource` resources and data sources' `output` field defaults to the readonly fields when the `response_export_values` is not specified.  
+  When run the `terraform plan` command, the output will show the computed field `output` has changed.
+
+  How to fix:
+  1. Run `terraform refresh` to update the state file.
+  2. Specify the `disable_default_output = true` in the provider block to disable the default output.
+
+- `azapi_resource_list` data source's `output` field defaults to the response when the `response_export_values` is not specified.
+
+  How to fix:
+  1. Run `terraform refresh` to update the state file.
+  2. Specify the `disable_default_output = true` in the provider block to disable the default output.

examples/data-sources/azapi_resource_list/data-source.tf

@@ -11,15 +11,20 @@ provider "azapi" {
 }
 
 data "azapi_resource_list" "listBySubscription" {
-  type                   = "Microsoft.Automation/automationAccounts@2021-06-22"
-  parent_id              = "/subscriptions/00000000-0000-0000-0000-000000000000"
-  response_export_values = ["*"]
+  type      = "Microsoft.Automation/automationAccounts@2021-06-22"
+  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000"
+  response_export_values = {
+    "values" = "value[].{name: name, publicNetworkAccess: properties.publicNetworkAccess}"
+    "names"  = "value[].name"
+  }
 }
 
 data "azapi_resource_list" "listByResourceGroup" {
-  type                   = "Microsoft.Automation/automationAccounts@2021-06-22"
-  parent_id              = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1"
-  response_export_values = ["*"]
+  type      = "Microsoft.Automation/automationAccounts@2021-06-22"
+  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1"
+  response_export_values = {
+    "names" = "value[].name"
+  }
 }
 
 data "azapi_resource_list" "listSubnetsByVnet" {

internal/docstrings/response_export_values.go

@@ -27,6 +27,54 @@ const (
 	}
 	%s%s%s
 
+To learn more about JMESPath, visit [JMESPath](https://jmespath.org/).
+`
+
+	responseExportValuesForResourceListStr = `The attribute can accept either a list or a map.
+
+- **List**: A list of paths that need to be exported from the response body. Setting it to %s["*"]%s will export the full response body. Here's an example. If it sets to %s["value"]%s, it will set the following HCL object to the computed property output.
+
+	%s%s%stext
+	{
+	  "value" = [
+		{
+		  "id" = "/subscriptions/000000/resourceGroups/demo-rg/providers/Microsoft.Automation/automationAccounts/example"
+		  "location" = "eastus2"
+		  "name" = "example"
+		  "properties" = {
+			"creationTime" = "2024-10-11T08:18:38.737+00:00"
+			"disableLocalAuth" = false
+			"lastModifiedTime" = "2024-10-11T08:18:38.737+00:00"
+			"publicNetworkAccess" = true
+		  }
+		  "tags" = {}
+		  "type" = "Microsoft.Automation/AutomationAccounts"
+		}
+	  ]
+	}
+	%s%s%s
+
+- **Map**: A map where the key is the name for the result and the value is a JMESPath query string to filter the response. Here's an example. If it sets to %s{"values": "value[].{name: name, publicNetworkAccess: properties.publicNetworkAccess}", "names": "value[].name"}%s, it will set the following HCL object to the computed property output.
+
+	%s%s%stext
+	{
+		"names" = [
+			"example",
+			"fredaccount01",
+		]
+		"values" = [
+			{
+			  "name" = "example"
+			  "publicNetworkAccess" = true
+			},
+			{
+			  "name" = "fredaccount01"
+			  "publicNetworkAccess" = null
+			},
+		]
+	}
+	%s%s%s
+
 To learn more about JMESPath, visit [JMESPath](https://jmespath.org/).
 `
 )
@@ -35,3 +83,8 @@ To learn more about JMESPath, visit [JMESPath](https://jmespath.org/).
 func ResponseExportValues() string {
 	return addBackquotes(responseExportValuesStr)
 }
+
+// ResponseExportValuesForResourceList returns the docstring for the response_export_values schema attribute for the resource list data source.
+func ResponseExportValuesForResourceList() string {
+	return addBackquotes(responseExportValuesForResourceListStr)
+}

internal/services/azapi_data_plane_resource.go

@@ -156,7 +156,13 @@ func (r *DataPlaneResource) Schema(ctx context.Context, request resource.SchemaR
 				MarkdownDescription: docstrings.IgnoreMissingProperty(),
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional: true,
+				PlanModifiers: []planmodifier.Dynamic{
+					myplanmodifier.DynamicUseStateWhen(dynamic.SemanticallyEqual),
+				},
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"retry": retry.SingleNestedAttribute(ctx),
 

internal/services/azapi_resource.go

@@ -222,7 +222,13 @@ func (r *AzapiResource) Schema(ctx context.Context, _ resource.SchemaRequest, re
 				MarkdownDescription: docstrings.IgnoreMissingProperty(),
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional: true,
+				PlanModifiers: []planmodifier.Dynamic{
+					myplanmodifier.DynamicUseStateWhen(dynamic.SemanticallyEqual),
+				},
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"locks": schema.ListAttribute{
 				ElementType: types.StringType,

internal/services/azapi_resource_action_data_source.go

@@ -97,7 +97,10 @@ func (r *ResourceActionDataSource) Schema(ctx context.Context, request datasourc
 				},
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional:            true,
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"output": schema.DynamicAttribute{
 				Computed:            true,

internal/services/azapi_resource_action_resource.go

@@ -154,7 +154,13 @@ func (r *ActionResource) Schema(ctx context.Context, request resource.SchemaRequ
 				MarkdownDescription: docstrings.Locks(),
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional: true,
+				PlanModifiers: []planmodifier.Dynamic{
+					myplanmodifier.DynamicUseStateWhen(dynamic.SemanticallyEqual),
+				},
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"output": schema.DynamicAttribute{
 				Computed:            true,

internal/services/azapi_resource_data_source.go

@@ -135,7 +135,10 @@ func (r *AzapiResourceDataSource) Schema(ctx context.Context, request datasource
 				},
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional:            true,
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"output": schema.DynamicAttribute{
 				Computed:            true,

internal/services/azapi_resource_list_data_source.go

@@ -72,7 +72,10 @@ func (r *ResourceListDataSource) Schema(ctx context.Context, request datasource.
 				MarkdownDescription: docstrings.ParentID(),
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional:            true,
+				MarkdownDescription: docstrings.ResponseExportValuesForResourceList(),
+			},
 
 			"output": schema.DynamicAttribute{
 				Computed:            true,

internal/services/azapi_update_resource.go

@@ -165,7 +165,13 @@ func (r *AzapiUpdateResource) Schema(ctx context.Context, request resource.Schem
 				MarkdownDescription: docstrings.IgnoreMissingProperty(),
 			},
 
-			"response_export_values": CommonAttributeResponseExportValues(),
+			"response_export_values": schema.DynamicAttribute{
+				Optional: true,
+				PlanModifiers: []planmodifier.Dynamic{
+					myplanmodifier.DynamicUseStateWhen(dynamic.SemanticallyEqual),
+				},
+				MarkdownDescription: docstrings.ResponseExportValues(),
+			},
 
 			"locks": schema.ListAttribute{
 				ElementType: types.StringType,

internal/services/common.go

@@ -6,12 +6,8 @@ import (
 	"os"
 	"time"
 
-	"github.com/Azure/terraform-provider-azapi/internal/docstrings"
 	"github.com/Azure/terraform-provider-azapi/internal/services/dynamic"
-	"github.com/Azure/terraform-provider-azapi/internal/services/myplanmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/attr"
-	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
-	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/types"
 )
 
@@ -25,16 +21,6 @@ func Retry404MaxElapsedTime() time.Duration {
 	return 2 * time.Minute
 }
 
-func CommonAttributeResponseExportValues() schema.DynamicAttribute {
-	return schema.DynamicAttribute{
-		Optional: true,
-		PlanModifiers: []planmodifier.Dynamic{
-			myplanmodifier.DynamicUseStateWhen(dynamic.SemanticallyEqual),
-		},
-		MarkdownDescription: docstrings.ResponseExportValues(),
-	}
-}
-
 func buildOutputFromBody(responseBody interface{}, modelResponseExportValues types.Dynamic, defaultResult interface{}) (types.Dynamic, error) {
 	if modelResponseExportValues.IsNull() {
 		if defaultResult == nil {

templates/guides/2.0-upgrade-guide.md

@@ -497,3 +497,16 @@ When you run `terraform plan`, you will see the following error message:
 
   How to fix:  
   Please set it to `true` explicitly if you want to authenticate using Managed Service Identity.
+
+- `azapi_resource`, `azapi_update_resource` resources and data sources' `output` field defaults to the readonly fields when the `response_export_values` is not specified.  
+  When run the `terraform plan` command, the output will show the computed field `output` has changed.
+
+  How to fix:
+  1. Run `terraform refresh` to update the state file.
+  2. Specify the `disable_default_output = true` in the provider block to disable the default output.
+
+- `azapi_resource_list` data source's `output` field defaults to the response when the `response_export_values` is not specified.
+
+  How to fix:
+  1. Run `terraform refresh` to update the state file.
+  2. Specify the `disable_default_output = true` in the provider block to disable the default output.