Skip to content

Commit

Permalink
Add armResourceIdentifier scalar to azure core (#407)
Browse files Browse the repository at this point in the history
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
  • Loading branch information
timotheeguerin and markcowl authored Mar 29, 2024
1 parent bf2a3a2 commit 2a6b486
Show file tree
Hide file tree
Showing 22 changed files with 401 additions and 153 deletions.
8 changes: 8 additions & 0 deletions .chronus/changes/azure-core-arm-id-2024-2-12-17-36-10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: feature
packages:
- "@azure-tools/typespec-autorest"
---

Add support for new `Azure.Core.armResourceManager` scalar
8 changes: 8 additions & 0 deletions .chronus/changes/azure-core-arm-id-2024-2-12-17-36-8.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: feature
packages:
- "@azure-tools/typespec-azure-core"
---

Adding new `armResourceIdentifier` scalar to represent an Arm ID
8 changes: 8 additions & 0 deletions .chronus/changes/azure-core-arm-id-2024-2-12-17-36-9.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: deprecation
packages:
- "@azure-tools/typespec-azure-resource-manager"
---

Deprecate `ResourceIdentifier` in favor of new `Azure.Core.armResourceIdentifier`
6 changes: 3 additions & 3 deletions docs/howtos/ARM/resource-type.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ enum EmployeeProvisioningState {
scalar EmployeeLevel extends int32;
scalar EmployeeResourceId
extends ResourceIdentifier<[
extends Azure.Core.armResourceIdentifier<[
{
type: "Microsoft.HR/employees",
}
Expand Down Expand Up @@ -343,14 +343,14 @@ It is often the case that resources need to reference other resources to provide

```typespec
scalar EmployeeResourceId
extends ResourceIdentifier<[
extends Azure.Core.armResourceIdentifier<[
{
type: "Microsoft.HR/employees",
}
]>;
scalar NetworkInterfaceId
extends ResourceIdentifier<[
extends Azure.Core.armResourceIdentifier<[
{
type: "Microsoft.Network/networkInterfaces",
},
Expand Down
32 changes: 32 additions & 0 deletions docs/libraries/azure-core/reference/data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,19 @@ model Azure.Core.AadTokenAuthFlow<Scopes, AuthUrl, TokenUrl>
| tokenUrl | `TokenUrl` | |
| scopes | `Scopes` | |

### `ArmResourceIdentifierAllowedResource` {#Azure.Core.ArmResourceIdentifierAllowedResource}

```typespec
model Azure.Core.ArmResourceIdentifierAllowedResource
```

#### Properties

| Name | Type | Description |
| ------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type | `string` | The type of resource that is being referred to. For example Microsoft.Network/virtualNetworks or Microsoft.Network/virtualNetworks/subnets. See Example Types for more examples. |
| scopes? | `Core.ArmResourceDeploymentScope[]` | An array of scopes. If not specified, the default scope is ["ResourceGroup"].<br />See [Allowed Scopes](https://github.com/Azure/autorest/tree/main/docs/extensions#allowed-scopes). |

### `AzureApiKeyAuthentication` {#Azure.Core.AzureApiKeyAuthentication}

Azure API Key Authentication using the "Ocp-Apim-Subscription-Key" hea
Expand Down Expand Up @@ -466,6 +479,12 @@ Supported versions of Azure.Core TypeSpec building blocks.
enum Azure.Core.Versions
```

### `ArmResourceDeploymentScope` {#Azure.Core.ArmResourceDeploymentScope}

```typespec
union Azure.Core.ArmResourceDeploymentScope
```

### `PollingOptionKind` {#Azure.Core.PollingOptionKind}

The available kinds of polling options
Expand All @@ -482,6 +501,19 @@ Repeatability Result header options
union Azure.Core.RepeatabilityResult
```

### `armResourceIdentifier` {#Azure.Core.armResourceIdentifier}

A type definition that refers the id to an Azure Resource Manager resource.

Sample usage:
otherArmId: ResourceIdentifier;
networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]>
vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>

```typespec
scalar Azure.Core.armResourceIdentifier
```

### `azureLocation` {#Azure.Core.azureLocation}

Represents an Azure geography region where supported resource providers live.
Expand Down
1 change: 1 addition & 0 deletions docs/libraries/azure-core/reference/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,7 @@ npm install --save-peer @azure-tools/typespec-azure-core

- [`AadOauth2Auth`](./data-types.md#Azure.Core.AadOauth2Auth)
- [`AadTokenAuthFlow`](./data-types.md#Azure.Core.AadTokenAuthFlow)
- [`ArmResourceIdentifierAllowedResource`](./data-types.md#Azure.Core.ArmResourceIdentifierAllowedResource)
- [`AzureApiKeyAuthentication`](./data-types.md#Azure.Core.AzureApiKeyAuthentication)
- [`ClientRequestIdHeader`](./data-types.md#Azure.Core.ClientRequestIdHeader)
- [`ConditionalRequestHeaders`](./data-types.md#Azure.Core.ConditionalRequestHeaders)
Expand Down
63 changes: 4 additions & 59 deletions docs/libraries/azure-resource-manager/reference/data-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ model Azure.ResourceManager.CustomerManagedKeyEncryption
| Name | Type | Description |
| ------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keyEncryptionIdentity? | [`KeyEncryptionIdentity`](./data-types.md#Azure.ResourceManager.KeyEncryptionIdentity) | The type of identity to use. Values can be systemAssignedIdentity, userAssignedIdentity, or delegatedResourceIdentity. |
| userAssignedIdentityResourceId? | [`ResourceIdentifier`](#Azure.ResourceManager.ResourceIdentifier) | User assigned identity to use for accessing key encryption key Url. Ex: /subscriptions/fa5fc227-a624-475e-b696-cdd604c735bc/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId. Mutually exclusive with identityType systemAssignedIdentity. |
| userAssignedIdentityResourceId? | `Core.armResourceIdentifier` | User assigned identity to use for accessing key encryption key Url. Ex: /subscriptions/fa5fc227-a624-475e-b696-cdd604c735bc/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId. Mutually exclusive with identityType systemAssignedIdentity. |
| federatedClientId? | `Core.uuid` | application client identity to use for accessing key encryption key Url in a different tenant. Ex: f83c6b1b-4d34-47e4-bb34-9d83df58b540 |
| delegatedIdentityClientId? | `Core.uuid` | delegated identity to use for accessing key encryption key Url. Ex: /subscriptions/fa5fc227-a624-475e-b696-cdd604c735bc/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId. Mutually exclusive with identityType systemAssignedIdentity and userAssignedIdentity - internal use only. |

Expand Down Expand Up @@ -642,9 +642,9 @@ model Azure.ResourceManager.PrivateEndpoint

#### Properties

| Name | Type | Description |
| ---- | ----------------------------------------------------------------- | -------------------------------------------- |
| id? | [`ResourceIdentifier`](#Azure.ResourceManager.ResourceIdentifier) | The resource identifier for private endpoint |
| Name | Type | Description |
| ---- | ---------------------------- | -------------------------------------------- |
| id? | `Core.armResourceIdentifier` | The resource identifier for private endpoint |

### `PrivateEndpointConnection` {#Azure.ResourceManager.PrivateEndpointConnection}

Expand Down Expand Up @@ -860,22 +860,6 @@ model Azure.ResourceManager.ResourceGroupParameter
| ----------------- | -------- | ------------------------------------------------------------- |
| resourceGroupName | `string` | The name of the resource group. The name is case insensitive. |

### `ResourceIdentifierAllowedResource` {#Azure.ResourceManager.ResourceIdentifierAllowedResource}

Used in ResourceIdentifier definition to represent a particular type of Azure Resource Manager resource, enabling constraints based on resource type.
See [link](https://github.com/Azure/autorest/tree/main/docs/extensions#schema)

```typespec
model Azure.ResourceManager.ResourceIdentifierAllowedResource
```

#### Properties

| Name | Type | Description |
| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type | `string` | The type of resource that is being referred to. For example Microsoft.Network/virtualNetworks or Microsoft.Network/virtualNetworks/subnets. See Example Types for more examples. |
| scopes? | `string[]` | An array of scopes. If not specified, the default scope is ["ResourceGroup"].<br />See [Allowed Scopes](https://github.com/Azure/autorest/tree/main/docs/extensions#allowed-scopes). |

### `ResourceInstanceParameters` {#Azure.ResourceManager.ResourceInstanceParameters}

The dynamic parameters of a resource instance - pass in the proper base type to indicate
Expand Down Expand Up @@ -1151,45 +1135,6 @@ Supported versions of Azure.ResourceManager building blocks.
enum Azure.ResourceManager.Versions
```

### `ResourceIdentifier` {#Azure.ResourceManager.ResourceIdentifier}

A type definition that refers the id to an Azure Resource Manager resource.

Sample usage:
otherArmId: ResourceIdentifier;
networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]>
vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>

```typespec
scalar Azure.ResourceManager.ResourceIdentifier
```

### `ResourceIdentifier` {#Azure.ResourceManager.ResourceIdentifier}

A type definition that refers the id to an Azure Resource Manager resource.

Sample usage:
otherArmId: ResourceIdentifier;
networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]>
vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>

```typespec
scalar Azure.ResourceManager.ResourceIdentifier
```

### `ResourceIdentifier` {#Azure.ResourceManager.ResourceIdentifier}

A type definition that refers the id to an Azure Resource Manager resource.

Sample usage:
otherArmId: ResourceIdentifier;
networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]>
vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>

```typespec
scalar Azure.ResourceManager.ResourceIdentifier
```

## Azure.ResourceManager.CommonTypes

### `Versions` {#Azure.ResourceManager.CommonTypes.Versions}
Expand Down
1 change: 0 additions & 1 deletion docs/libraries/azure-resource-manager/reference/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,6 @@ npm install --save-peer @azure-tools/typespec-azure-resource-manager
- [`ProxyResource`](./data-types.md#Azure.ResourceManager.ProxyResource)
- [`ResourceGroupLocationResource`](./data-types.md#Azure.ResourceManager.ResourceGroupLocationResource)
- [`ResourceGroupParameter`](./data-types.md#Azure.ResourceManager.ResourceGroupParameter)
- [`ResourceIdentifierAllowedResource`](./data-types.md#Azure.ResourceManager.ResourceIdentifierAllowedResource)
- [`ResourceInstanceParameters`](./data-types.md#Azure.ResourceManager.ResourceInstanceParameters)
- [`ResourceKind`](./data-types.md#Azure.ResourceManager.ResourceKind)
- [`ResourceListResult`](./data-types.md#Azure.ResourceManager.ResourceListResult)
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/arm/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The following models are used for different purposes:
| Model | Category | Notes |
| -------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ArmResource | Base | Defines the base model with common properties for all ARM resources. |
| ResourceIdentifier<T\> | Common | A type definition that refers the id to an ARM resource. Sample usage: ` otherArmId: ResourceIdentifier; networkId: ResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]> vmIds: ResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>` |
| armResourceIdentifier<T\> | Common | A type definition that refers the id to an ARM resource. Sample usage: ` otherArmId: ResourceIdentifier; networkId: armResourceIdentifier<[{type:"\\Microsoft.Network\\vnet"}]> vmIds: armResourceIdentifier<[{type:"\\Microsoft.Compute\\vm", scopes["*"]}]>` |
| DefaultProvisioningStateProperty | Common | Contains a default provisioningState property to be spread into resource property types. Available values: `Succeeded`, `Failed`, and `Cancelled` |
| ManagedServiceIdentity | Common | The managed service identities envelope. |
| EntityTag | Common | The eTag property envelope. |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ interface Operations extends Azure.ResourceManager.Operations {}
@doc("A reference to a resource of type title.")
@pattern("\\/subscriptions\\/[a-z0-9\\-]+\\/resourceGroups\\/[^\\/]+\\/providers\\/Microsoft\\.PlayFab\\/titles\\/[^\\/]+")
scalar TitleReference
extends ResourceIdentifier<[
extends Azure.Core.armResourceIdentifier<[
{
type: "Microsoft.Playfab/titles",
}
Expand All @@ -33,7 +33,7 @@ scalar TitleReference
@doc("A reference to a player database resource.")
@pattern("\\/subscriptions\\/[a-z0-9\\-]+\\/resourceGroups\\/[^\\/]+\\/providers\\/Microsoft\\.PlayFab\\/playerDatabases\\/[^\\/]+")
scalar PlayerDatabaseReference
extends ResourceIdentifier<[
extends Azure.Core.armResourceIdentifier<[
{
type: "Microsoft.Playfab/playerDatabases",
}
Expand Down
7 changes: 7 additions & 0 deletions packages/typespec-autorest/src/openapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import {
PagedResultMetadata,
UnionEnum,
extractLroStates,
getArmResourceIdentifierConfig,
getAsEmbeddingVector,
getLroMetadata,
getPagedResult,
Expand Down Expand Up @@ -1825,6 +1826,12 @@ function createOAPIEmitter(
if (getAsEmbeddingVector(program, type as Model) !== undefined) {
emitObject["x-ms-embedding-vector"] = true;
}
if (type.kind === "Scalar") {
const ext = getArmResourceIdentifierConfig(program, type);
if (ext) {
emitObject["x-ms-arm-id-details"] = ext;
}
}
if (extensions) {
for (const key of extensions.keys()) {
emitObject[key] = extensions.get(key);
Expand Down
19 changes: 0 additions & 19 deletions packages/typespec-autorest/test/azure-core-operations.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -138,22 +138,3 @@ describe("typespec-autorest: Azure.Core.ResourceOperations", () => {
checkParams(params, "/widgets");
});
});

describe("typespec-autorest: Azure.Core concepts", () => {
it("defines embedding vector models", async () => {
const result = await openApiFor(`
${wrapperCode}
model Foo is Azure.Core.EmbeddingVector<int32>;
`);
const model = result.definitions["Foo"];
deepStrictEqual(model, {
type: "array",
description: "A vector embedding frequently used in similarity search.",
"x-ms-embedding-vector": true,
items: {
type: "integer",
format: "int32",
},
});
});
});
64 changes: 64 additions & 0 deletions packages/typespec-autorest/test/azure-core-types.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
import { deepStrictEqual } from "assert";
import { describe, it } from "vitest";
import { openApiFor } from "./test-host.js";

const base = `
@service
@useDependency(Azure.Core.Versions.v1_0_Preview_2)
namespace MyService;
`;

describe("EmbeddingVector", () => {
it("defines embedding vector models", async () => {
const result = await openApiFor(`
${base}
model Foo is Azure.Core.EmbeddingVector<int32>;
`);
const model = result.definitions["Foo"];
deepStrictEqual(model, {
type: "array",
description: "A vector embedding frequently used in similarity search.",
"x-ms-embedding-vector": true,
items: {
type: "integer",
format: "int32",
},
});
});
});

describe("armResourceIdentifier", () => {
it("without config", async () => {
const result = await openApiFor(`
${base}
scalar Foo extends Azure.Core.armResourceIdentifier;
`);
const model = result.definitions["Foo"];
deepStrictEqual(model, {
type: "string",
format: "arm-id",
description: "A type definition that refers the id to an Azure Resource Manager resource.",
});
});

it("with config", async () => {
const result = await openApiFor(`
${base}
scalar Foo extends Azure.Core.armResourceIdentifier<[{type:"Microsoft.RP/type", scopes:["tenant", "resourceGroup"]}]>;
`);
const model = result.definitions["Foo"];
deepStrictEqual(model, {
type: "string",
format: "arm-id",
description: "A type definition that refers the id to an Azure Resource Manager resource.",
"x-ms-arm-id-details": {
allowedResources: [
{
scopes: ["tenant", "resourceGroup"],
type: "Microsoft.RP/type",
},
],
},
});
});
});
10 changes: 10 additions & 0 deletions packages/typespec-azure-core/lib/decorators.tsp
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,16 @@ namespace Azure {
entity: TypeSpec.Reflection.Model,
type: TypeSpec.Reflection.Scalar
);

model ArmResourceIdentifierConfigOptions {
allowedResources: ArmResourceIdentifierAllowedResource[];
}

/** Configuration for the armResourceIdentifier scalar */
extern dec armResourceIdentifierConfig(
target: Scalar,
options: ArmResourceIdentifierConfigOptions
);
}
}
}
Expand Down
Loading

0 comments on commit 2a6b486

Please sign in to comment.