Skip to content

Commit

Permalink
Remove azcertificates handwritten API (Azure#18502)
Browse files Browse the repository at this point in the history
  • Loading branch information
chlowell authored Jul 5, 2022
1 parent 7fa40d8 commit 03c1e02
Show file tree
Hide file tree
Showing 50 changed files with 11,478 additions and 23,974 deletions.
100 changes: 37 additions & 63 deletions sdk/keyvault/azcertificates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,8 +110,8 @@ Constructing the client also requires your vault's URL, which you can get from t

```go
import (
"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
)

func main() {
Expand All @@ -120,10 +120,7 @@ func main() {
// TODO: handle error
}

client, err := azcertificates.NewClient("https://<TODO: your vault name>.vault.azure.net", credential, nil)
if err != nil {
// TODO: handle error
}
client := azcertificates.NewClient("https://<TODO: your vault name>.vault.azure.net", credential, nil)
}
```

Expand All @@ -141,25 +138,21 @@ illustrated in the [examples](#examples) below.
This section contains code snippets covering common tasks:
* [Create a Certificate](#create-a-certificate)
* [Delete a Certificate](#delete-a-certificate)
* [List Properties of Certificates](#list-properties-of-certificates)
* [List Certificates](#list-certificates)
* [Retrieve a Certificate](#retrieve-a-certificate)
* [Update Properties of an existing Certificate](#update-properties-of-an-existing-certificate)
* [Update Certificate Metadata](#update-certificate-metadata)

### Create a Certificate

[BeginCreateCertificate](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.BeginCreateCertificate)
[CreateCertificate](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.CreateCertificate)
creates a certificate to be stored in the Azure Key Vault. If a certificate with the same name already exists, a new
version of the certificate is created. Before creating a certificate, a management policy for the certificate can be
created or our default policy will be used. This method returns a poller object that enables waiting for the operation
to complete.
version of the certificate is created.

```go
import (
"context"
"fmt"
"time"

"github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
Expand All @@ -170,34 +163,23 @@ func main() {
if err != nil {
// TODO: handle error
}
client, err := azcertificates.NewClient("https://<TODO: your vault name>.vault.azure.net", credential, nil)
if err != nil {
// TODO: handle error
}
client := azcertificates.NewClient("https://<TODO: your vault name>.vault.azure.net", credential, nil)

resp, err := client.BeginCreateCertificate(context.TODO(), "certificateName", azcertificates.Policy{
IssuerParameters: &azcertificates.IssuerParameters{
IssuerName: to.Ptr("Self"),
},
X509Properties: &azcertificates.X509CertificateProperties{
Subject: to.Ptr("CN=DefaultPolicy"),
createParams := azcertificates.CreateCertificateParameters{
// this policy is suitable for a self-signed certificate
CertificatePolicy: &azcertificates.CertificatePolicy{
IssuerParameters: &azcertificates.IssuerParameters{Name: (*string)(to.Ptr("self"))},
X509CertificateProperties: &azcertificates.X509CertificateProperties{Subject: to.Ptr("CN=DefaultPolicy")},
},
}, nil)
if err != nil {
// TODO: handle error
}

finalResponse, err := resp.PollUntilDone(context.TODO(), &runtime.PollUntilDoneOptions{Frequency: time.Second})
resp, err := client.CreateCertificate(context.TODO(), "certificateName", createParams, nil)
if err != nil {
// TODO: handle error
}

fmt.Println("Created a certificate with ID: ", *finalResponse.ID)
fmt.Println("Created a certificate with ID:", *resp.ID)
}
```
If you would like to check the status of your certificate creation, you can call `Poll(ctx context.Context)` on the poller or
[GetCertificateOperation](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.GetCertificateOperation)
with the name of the certificate.

### Retrieve a Certificate

Expand All @@ -207,9 +189,10 @@ retrieves the latest version of a certificate previously stored in the Key Vault
```go
import (
"context"
"fmt"

"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
)

func main() {
Expand All @@ -223,24 +206,20 @@ func main() {
// TODO: handle error
}

resp, err := client.GetCertificate(context.TODO(), "myCertName", nil)
if err != nil {
// TODO: handle error
}

// optionally you can get a specific version
resp, err = client.GetCertificate(context.TODO(), "myCertName", &azcertificates.GetCertificateOptions{Version: "myCertVersion"})
// passing an empty string for the version gets the latest version of the certificate
resp, err := client.GetCertificate(context.TODO(), "certName", "", nil)
if err != nil {
// TODO: handle error
}
fmt.Println(*resp.ID)
}
```


### Update properties of an existing Certificate
### Update Certificate metadata

[UpdateCertificateProperties](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.UpdateCertificateProperties)
updates a certificate previously stored in the Key Vault.
[UpdateCertificate](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.UpdateCertificate)
updates a certificate's metadata.

```go
import (
Expand All @@ -263,32 +242,27 @@ func main() {
// TODO: handle error
}

resp, err := client.GetCertificate(context.TODO(), "myCertName", nil)
if err != nil {
// TODO: handle error
updateParams := azcertificates.UpdateCertificateParameters{
CertificateAttributes: &azcertificates.CertificateAttributes{Enabled: to.Ptr(false)},
}

resp.Properties.Enabled = to.Ptr(false)
updateResp, err := client.UpdateCertificateProperties(context.TODO(), *resp.Properties, nil)
// passing an empty string for the version updates the latest version of the certificate
resp, err := client.UpdateCertificate(context.TODO(), "certName", "", updateParams, nil)
if err != nil {
// TODO: handle error
}
fmt.Printf("Set Enabled to %v for certificate with name %s\n", *&updateResp.Properties.Enabled, *resp.ID)
fmt.Println(*resp.ID)
}
```

### Delete a Certificate

[BeginDeleteCertificate](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.BeginDeleteCertificate)
requests Key Vault delete a certificate, returning a poller which allows you to wait for the deletion to finish. Waiting is helpful when you want to purge (permanently delete) the certificate as soon as possible.
[DeleteCertificate](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.DeleteCertificate) requests that Key Vault delete a certificate. It returns when Key Vault has begun deleting the certificate. Deletion can take several seconds to complete, so it may be necessary to wait before performing other operations on the deleted certificate.

```go
import (
"context"
"fmt"
"time"

"github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates"
)
Expand All @@ -304,22 +278,22 @@ func main() {
// TODO: handle error
}

pollerResp, err := client.BeginDeleteCertificate(context.TODO(), "certToDelete", nil)
if err != nil {
// TODO: handle error
}
finalResp, err := pollerResp.PollUntilDone(context.TODO(), &runtime.PollUntilDoneOptions{Frequency: time.Second})
// DeleteCertificate returns when Key Vault has begun deleting the certificate. That can take several
// seconds to complete, so it may be necessary to wait before performing other operations on the
// deleted certificate.
resp, err := client.DeleteCertificate(context.TODO(), "certName", nil)
if err != nil {
// TODO: handle error
}

fmt.Println("Deleted certificate with ID: ", *finalResp.ID)
// In a soft-delete enabled vault, deleted resources can be recovered until they're purged (permanently deleted).
fmt.Printf("Certificate will be purged at %v", *resp.ScheduledPurgeDate)
}
```

### List Certificates

[NewListPropertiesOfCertificatesPager](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.NewListPropertiesOfCertificatesPager) creates a pager that lists the properties of all certificates in the client's vault.
[NewListCertificatesPager](https://aka.ms/azsdk/go/keyvault-certificates/docs#Client.NewListCertificatesPager) creates a pager that lists all certificates in the vault.

```go
import (
Expand All @@ -341,13 +315,13 @@ func main() {
// TODO: handle error
}

pager := client.NewListPropertiesOfCertificatesPager(nil)
pager := client.NewListCertificatesPager(nil)
for pager.More() {
page, err := pager.NextPage(context.TODO())
if err != nil {
// TODO: handle error
}
for _, cert := range page.Certificates {
for _, cert := range page.Value {
fmt.Println(*cert.ID)
}
}
Expand Down
141 changes: 119 additions & 22 deletions sdk/keyvault/azcertificates/autorest.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,130 @@
## Go

These settings apply only when `--go` is specified on the command line.

``` yaml
```yaml
clear-output-folder: false
export-clients: true
go: true
version: "^3.0.0"
input-file:
- https://github.com/Azure/azure-rest-api-specs/blob/e2ef44b87405b412403ccb005bfb3975411adf60/specification/keyvault/data-plane/Microsoft.KeyVault/stable/7.3/certificates.json
input-file: https://github.com/Azure/azure-rest-api-specs/blob/37cd8dfac3c570a24bb645b31c012d12efb760df/specification/keyvault/data-plane/Microsoft.KeyVault/stable/7.3/certificates.json
license-header: MICROSOFT_MIT_NO_VERSION
clear-output-folder: true
output-folder: internal/generated
module: github.com/Azure/azure-sdk-for-go/sdk/keyvault/azcertificates
openapi-type: "data-plane"
output-folder: ../azcertificates
override-client-name: Client
security: "AADToken"
security-scopes: "https://vault.azure.net/.default"
use: "@autorest/[email protected]"
module-version: 0.4.0
export-clients: true
security-scopes: "https://vault.azure.net/.default"
use: "@autorest/[email protected]"
version: "^3.0.0"

# remove the empty certificateVersion path param check. it's legal for KV but can't be described in OpenAPI
directive:
- from: constants.go
# delete unused model
- remove-model: PendingCertificateSigningRequestResult

# make vault URL a parameter of the client constructor
- from: swagger-document
where: $["x-ms-parameterized-host"]
transform: $.parameters[0]["x-ms-parameter-location"] = "client"

# rename parameter models to match their methods
- rename-model:
from: CertificateCreateParameters
to: CreateCertificateParameters
- rename-model:
from: CertificateImportParameters
to: ImportCertificateParameters
- rename-model:
from: CertificateIssuerSetParameters
to: SetCertificateIssuerParameters
- rename-model:
from: CertificateIssuerUpdateParameters
to: UpdateCertificateIssuerParameters
- rename-model:
from: CertificateMergeParameters
to: MergeCertificateParameters
- rename-model:
from: CertificateOperationUpdateParameter
to: UpdateCertificateOperationParameter
- rename-model:
from: CertificateRestoreParameters
to: RestoreCertificateParameters
- rename-model:
from: CertificateUpdateParameters
to: UpdateCertificateParameters

# rename paged operations from Get* to List*
- rename-operation:
from: GetCertificates
to: ListCertificates
- rename-operation:
from: GetCertificateIssuers
to: ListCertificateIssuers
- rename-operation:
from: GetCertificateVersions
to: ListCertificateVersions
- rename-operation:
from: GetDeletedCertificates
to: ListDeletedCertificates

# Maxresults -> MaxResults
- from: swagger-document
where: $.paths..parameters..[?(@.name=='maxresults')]
transform: $["x-ms-client-name"] = "MaxResults"

# capitalize acronyms
- where-model: CertificateBundle
transform: $.properties.cer["x-ms-client-name"] = "CER"
- where-model: CertificateBundle
transform: $.properties.kid["x-ms-client-name"] = "KID"
- where-model: CertificateBundle
transform: $.properties.sid["x-ms-client-name"] = "SID"
- where-model: CertificateOperation
transform: $.properties.csr["x-ms-client-name"] = "CSR"
- where-model: SubjectAlternativeNames
transform: $.properties.upns["x-ms-client-name"] = "UPNs"
- where-model: X509CertificateProperties
transform: $.properties.ekus["x-ms-client-name"] = "EKUs"

# delete unused KeyVaultError
- from: models.go
where: $
transform: >-
return $.
replace(/moduleName\s+=\s+"generated"/, `ModuleName = "azcertificates"`).
replace(/moduleVersion\s+=/, `ModuleVersion =`);
- from: keyvault_client.go
transform: return $.replace(/(?:\/\/.*\s)+type KeyVaultError.+\{(?:\s.+\s)+\}\s/g, "");
- from: models_serde.go
where: $
transform: >-
return $.
replaceAll(/\sif certificateVersion == "" \{\s+return nil, errors\.New\("parameter certificateVersion cannot be empty"\)\s+\}\s/g, ``);
transform: return $.replace(/(?:\/\/.*\s)+func \(\w \*?KeyVaultError\).*\{\s(?:.+\s)+\}\s/g, "");

# delete the Attributes model defined in common.json (it's used only with allOf)
- from: models.go
where: $
transform: return $.replace(/(?:\/\/.*\s)+type Attributes.+\{(?:\s.+\s)+\}\s/, "");
- from: models_serde.go
where: $
transform: return $.replace(/(?:\/\/.*\s)+func \(a \*?Attributes\).*\{\s(?:.+\s)+\}\s/g, "");

# delete generated constructor
- from: client.go
where: $
transform: return $.replace(/(?:\/\/.*\s)+func NewClient.+\{\s(?:.+\s)+\}\s/, "");

# delete the version path param check (version == "" is legal for Key Vault but indescribable by OpenAPI)
- from: client.go
where: $
transform: return $.replace(/\sif certificateVersion == "" \{\s+.+certificateVersion cannot be empty"\)\s+\}\s/g, "");

# delete client name prefix from method options and response types
- from:
- client.go
- models.go
- response_types.go
where: $
transform: return $.replace(/Client(\w+)((?:Options|Response))/g, "$1$2");

# make cert IDs a convenience type so we can add parsing methods
# (specifying models because others have "ID" fields whose values aren't cert IDs)
- from: models.go
where: $
transform: return $.replace(/(type (?:Deleted)?Certificate(?:Bundle|Item) struct \{(?:\s.+\s)+\sID \*)string/g, "$1ID")

# remove "certificate" prefix from some method parameter names
- from: client.go
- where: $
- transform: return $.replace(/certificate((?:Name|Policy|Version)) string/g, (match) => { return match[0].toLowerCase() + match.substr(1); })
```
Loading

0 comments on commit 03c1e02

Please sign in to comment.