feat: add Explorer query export to csv API

Author: sebasslash

explorer.go

@@ -4,9 +4,11 @@
 package tfe
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"net/url"
+	"strings"
 	"time"
 )
 
@@ -25,6 +27,8 @@ type Explorer interface {
 	QueryProviders(ctx context.Context, organization string, options ExplorerQueryOptions) (*ExplorerProviderViewList, error)
 	// Query information about Terraform version usage within an organization.
 	QueryTerraformVersions(ctx context.Context, organization string, options ExplorerQueryOptions) (*ExplorerTerraformVersionViewList, error)
+	// Download a full, unpaged export of query results in CSV format.
+	ExportToCSV(ctx context.Context, organization string, options ExplorerQueryOptions) ([]byte, error)
 }
 
 type explorer struct {
@@ -69,7 +73,7 @@ type ExplorerQueryFilter struct {
 	Value    string
 }
 
-func (eqf *ExplorerQueryFilter) toQueryParam() (string, string) {
+func (eqf *ExplorerQueryFilter) toKeyValue() (string, string) {
 	key := fmt.Sprintf("filter[%d][%s][%s][0]", eqf.Index, eqf.Name, eqf.Operator)
 	return key, eqf.Value
 }
@@ -78,13 +82,30 @@ func (eqf *ExplorerQueryFilter) toQueryParam() (string, string) {
 type ExplorerQueryOptions struct {
 	ListOptions
 
-	View   ExplorerViewType `url:"type"`
-	Sort   string           `url:"sort,omitempty"`
-	Fields string           `url:"fields,omitempty"`
+	View ExplorerViewType `url:"type"`
+	Sort string           `url:"sort,omitempty"`
 
+	Fields  []string               `url:"-"`
 	Filters []*ExplorerQueryFilter `url:"-"`
 }
 
+func (eqo *ExplorerQueryOptions) extractFilters() map[string][]string {
+	filterParams := make(map[string][]string)
+	for _, filter := range eqo.Filters {
+		if filter != nil {
+			k, v := filter.toKeyValue()
+			filterParams[k] = []string{v}
+		}
+	}
+
+	// Append the fields query param, ensuring the correct view type is specified
+	if len(eqo.Fields) > 0 {
+		fieldsKey := fmt.Sprintf("fields[%s]", eqo.View)
+		filterParams[fieldsKey] = []string{strings.Join(eqo.Fields, ",")}
+	}
+	return filterParams
+}
+
 // WorkspaceView represents information about a workspace in the target
 // organization and any current runs associated with that workspace.
 type WorkspaceView struct {
@@ -251,16 +272,32 @@ func (e *explorer) QueryTerraformVersions(ctx context.Context, organization stri
 	return eql, nil
 }
 
-func (e *explorer) buildExplorerQueryRequest(organization string, options ExplorerQueryOptions) (*ClientRequest, error) {
-	filterParams := make(map[string][]string)
-	u := fmt.Sprintf("organizations/%s/explorer", url.QueryEscape(organization))
+// ExportToCSV performs an Explorer query and exports the results to CSV format.
+// https://developer.hashicorp.com/terraform/cloud-docs/api-docs/explorer#export-data-as-csv
+func (e *explorer) ExportToCSV(ctx context.Context, organization string, options ExplorerQueryOptions) ([]byte, error) {
+	filterParams := options.extractFilters()
 
-	for _, filter := range options.Filters {
-		if filter != nil {
-			k, v := filter.toQueryParam()
-			filterParams[k] = []string{v}
-		}
+	u := fmt.Sprintf("organizations/%s/explorer/export/csv", url.QueryEscape(organization))
+	req, err := e.client.NewRequestWithAdditionalQueryParams("GET", u, options, filterParams)
+	if err != nil {
+		return nil, err
 	}
 
+	// Override accept header
+	req.retryableRequest.Header.Set("Accept", "*/*")
+
+	buf := &bytes.Buffer{}
+	err = req.Do(ctx, buf)
+	if err != nil {
+		return nil, err
+	}
+
+	return buf.Bytes(), nil
+}
+
+func (e *explorer) buildExplorerQueryRequest(organization string, options ExplorerQueryOptions) (*ClientRequest, error) {
+	filterParams := options.extractFilters()
+
+	u := fmt.Sprintf("organizations/%s/explorer", url.QueryEscape(organization))
 	return e.client.NewRequestWithAdditionalQueryParams("GET", u, options, filterParams)
 }

explorer_integration_test.go

@@ -1,9 +1,12 @@
 package tfe
 
 import (
+	"bytes"
 	"context"
+	"encoding/csv"
 	"testing"
 
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
@@ -210,3 +213,35 @@ func TestExplorer_QueryWorkspaces(t *testing.T) {
 		}
 	})
 }
+
+func TestExplorer_ExportToCSV(t *testing.T) {
+	client := testClient(t)
+	ctx := context.Background()
+	organization := testExplorerOrganization(t)
+
+	csvResult, err := client.Explorer.ExportToCSV(ctx, organization, ExplorerQueryOptions{
+		View:   WorkspacesViewType,
+		Fields: []string{"workspace_name", "current_run_status"},
+		Filters: []*ExplorerQueryFilter{
+			{
+				Index:    0,
+				Name:     "current_run_status",
+				Operator: OpIs,
+				Value:    "applied",
+			},
+		},
+	})
+	require.NoError(t, err)
+	r := csv.NewReader(bytes.NewReader(csvResult))
+
+	header, err := r.Read()
+	require.NoError(t, err)
+	assert.Equal(t, len(header), 2)
+	// Fields come in the order specified in the request
+	assert.Equal(t, header[0], "workspace_name")
+	assert.Equal(t, header[1], "current_run_status")
+
+	rows, err := r.ReadAll()
+	require.NoError(t, err)
+	assert.Greater(t, len(rows), 0)
+}