Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update App Configuration management plane API description #23778

Merged

Conversation

jimmyca15
Copy link
Member

Update App Configuration management plane API description to declare intent behind key-value management plane API.

@jimmyca15 jimmyca15 requested review from zhenlan and jiayi11 May 1, 2023 16:45
@openapi-workflow-bot
Copy link

Hi, @jimmyca15 Thanks for your PR. I am workflow bot for review process. Here are some small tips.

  • Please ensure to do self-check against checklists in first PR comment.
  • PR assignee is the person auto-assigned and responsible for your current PR reviewing and merging.
  • For specs comparison cross API versions, Use API Specs Comparison Report Generator
  • If there is CI failure(s), to fix CI error(s) is mandatory for PR merging; or you need to provide justification in PR comment for explanation. How to fix?

  • Any feedback about review process or workflow bot, pls contact swagger and tools team. [email protected]

    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented May 1, 2023

    Swagger Validation Report

    ️️✔️BreakingChange succeeded [Detail] [Expand]
    There are no breaking changes.
    compared swaggers (via Oad v0.10.4)] new version base version
    appconfiguration.json 2023-03-01(0d8420e) 2023-03-01(main)
    ️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]
    There are no breaking changes.
    ️️✔️CredScan succeeded [Detail] [Expand]
    There is no credential detected.
    ️⚠️LintDiff: 0 Warnings warning [Detail]
    compared tags (via openapi-validator v2.0.0) new version base version
    package-2023-03-01 package-2023-03-01(0d8420e) package-2023-03-01(main)

    The following errors/warnings exist before current PR submission:

    Only 30 items are listed, please refer to log for more details.

    Rule Message
    CreateOperationAsyncResponseValidation An async PUT operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L154
    DeleteOperationAsyncResponseValidation An async DELETE operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L216
    LroLocationHeader A 202 response should include an Location response header.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L240
    LroPatch202 The async patch operation should return 202.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L289
    ResourceNameRestriction The resource name parameter 'privateEndpointConnectionName' should be defined with a 'pattern' restriction.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L562
    CreateOperationAsyncResponseValidation An async PUT operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L610
    DeleteOperationAsyncResponseValidation An async DELETE operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L673
    LroLocationHeader A 202 response should include an Location response header.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L704
    ResourceNameRestriction The resource name parameter 'groupName' should be defined with a 'pattern' restriction.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L770
    ResourceNameRestriction The resource name parameter 'keyValueName' should be defined with a 'pattern' restriction.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L819
    DeleteOperationAsyncResponseValidation An async DELETE operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L923
    LroLocationHeader A 202 response should include an Location response header.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L954
    PostOperationAsyncResponseValidation An async POST operation must set long running operation options 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1057
    LroLocationHeader A 202 response should include an Location response header.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1082
    TrackedResourcePatchOperation Tracked resource 'Replica' must have patch operation that at least supports the update of tags.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1205
    DeleteOperationAsyncResponseValidation An async DELETE operation is tracked via Azure-AsyncOperation header. Set 'final-state-via' property to 'location' on 'x-ms-long-running-operation-options'
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1320
    LroLocationHeader A 202 response should include an Location response header.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1353
    XmsParameterLocation The parameter 'SubscriptionIdParameter' is defined in global parameters section without 'x-ms-parameter-location' extension. This would add the parameter as the client property. Please ensure that this is exactly you want. If so, apply the extension 'x-ms-parameter-location': 'client'. Else, apply the extension 'x-ms-parameter-location': 'method'.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L2499
    XmsParameterLocation The parameter 'ApiVersionParameter' is defined in global parameters section without 'x-ms-parameter-location' extension. This would add the parameter as the client property. Please ensure that this is exactly you want. If so, apply the extension 'x-ms-parameter-location': 'client'. Else, apply the extension 'x-ms-parameter-location': 'method'.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L2525
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L154
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L216
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L260
    ⚠️ RequiredReadOnlySystemData The response of operation:'PrivateEndpointConnections_Get' is defined without 'systemData'. Consider adding the systemData to the response.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L563
    ⚠️ RequiredReadOnlySystemData The response of operation:'PrivateEndpointConnections_CreateOrUpdate' is defined without 'systemData'. Consider adding the systemData to the response.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L610
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L610
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L673
    ⚠️ RequiredReadOnlySystemData The response of operation:'KeyValues_Get' is defined without 'systemData'. Consider adding the systemData to the response.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L820
    ⚠️ RequiredReadOnlySystemData The response of operation:'KeyValues_CreateOrUpdate' is defined without 'systemData'. Consider adding the systemData to the response.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L867
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L923
    ⚠️ XmsLongRunningOperationOptions The x-ms-long-running-operation-options should be specified explicitly to indicate the type of response header to track the async operation.
    Location: Microsoft.AppConfiguration/stable/2023-03-01/appconfiguration.json#L1057
    ️️✔️Avocado succeeded [Detail] [Expand]
    Validation passes for Avocado.
    ️️✔️ApiReadinessCheck succeeded [Detail] [Expand]
    ️⚠️~[Staging] ServiceAPIReadinessTest: 0 Warnings warning [Detail]

    API Test is not triggered due to precheck failure. Check pipeline log for details.

    ️️✔️SwaggerAPIView succeeded [Detail] [Expand]
    ️️✔️CadlAPIView succeeded [Detail] [Expand]
    ️️✔️TypeSpecAPIView succeeded [Detail] [Expand]
    ️️✔️ModelValidation succeeded [Detail] [Expand]
    Validation passes for ModelValidation.
    ️️✔️SemanticValidation succeeded [Detail] [Expand]
    Validation passes for SemanticValidation.
    ️️✔️PoliCheck succeeded [Detail] [Expand]
    Validation passed for PoliCheck.
    ️️✔️PrettierCheck succeeded [Detail] [Expand]
    Validation passes for PrettierCheck.
    ️️✔️SpellCheck succeeded [Detail] [Expand]
    Validation passes for SpellCheck.
    ️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
    Validation passes for Lint(RPaaS).
    ️️✔️CadlValidation succeeded [Detail] [Expand]
    Validation passes for CadlValidation.
    ️️✔️TypeSpec Validation succeeded [Detail] [Expand]
    Validation passes for TypeSpec Validation.
    ️️✔️PR Summary succeeded [Detail] [Expand]
    Validation passes for Summary.
    Posted by Swagger Pipeline | How to fix these errors?

    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented May 1, 2023

    Swagger Generation Artifacts

    ️️✔️ApiDocPreview succeeded [Detail] [Expand]
     Please click here to preview with your @microsoft account. 
    ️️✔️SDK Breaking Change Tracking succeeded [Detail] [Expand]

    Breaking Changes Tracking



    ️⚠️ azure-sdk-for-python-track2 warning [Detail]
    • ⚠️Warning [Logs]Release - Generate from 32e5ec1. SDK Automation 14.0.0
      command	sh scripts/automation_init.sh ../azure-sdk-for-python_tmp/initInput.json ../azure-sdk-for-python_tmp/initOutput.json
      cmderr	[automation_init.sh] WARNING: Skipping azure-nspkg as it is not installed.
      command	sh scripts/automation_generate.sh ../azure-sdk-for-python_tmp/generateInput.json ../azure-sdk-for-python_tmp/generateOutput.json
      cmderr	[automation_generate.sh] npm notice
      cmderr	[automation_generate.sh] npm notice New minor version of npm available! 9.5.1 -> 9.6.6
      cmderr	[automation_generate.sh] npm notice Changelog: <https://github.com/npm/cli/releases/tag/v9.6.6>
      cmderr	[automation_generate.sh] npm notice Run `npm install -g [email protected]` to update!
      cmderr	[automation_generate.sh] npm notice
    • ️✔️track2_azure-mgmt-appconfiguration [View full logs]  [Release SDK Changes]
      info	[Changelog]
    ️❌ azure-sdk-for-net-track2 failed [Detail]
    • Failed [Logs]Release - Generate from 32e5ec1. SDK Automation 14.0.0
      command	pwsh ./eng/scripts/Automation-Sdk-Init.ps1 ../azure-sdk-for-net_tmp/initInput.json ../azure-sdk-for-net_tmp/initOutput.json
      command	pwsh ./eng/scripts/Invoke-GenerateAndBuildV2.ps1 ../azure-sdk-for-net_tmp/generateInput.json ../azure-sdk-for-net_tmp/generateOutput.json
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1mGeneratePackage: �[0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:712
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1mLine |
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m 712 | �[0m         �[36;1mGeneratePackage -projectFolder $projectFolder -sdkRootPath $s�[0m …
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m     | �[31;1m         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1m�[36;1m     | �[31;1mFailed to generate sdk. exit code: False
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[0m
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1mGet-ChildItem: �[0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:800
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1mLine |
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m 800 | �[0m … rtifacts += �[36;1mGet-ChildItem $artifactsPath -Filter *.nupkg -exclude *.s�[0m …
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m     | �[31;1m               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1m�[36;1m     | �[31;1mCannot find path
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m     | �[31;1m'/mnt/vss/_work/1/s/azure-sdk-for-net/artifacts/packages/Debug/' because
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m     | �[31;1mit does not exist.
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[0m
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1mGeneratePackage: �[0m/mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:712
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1mLine |
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m 712 | �[0m         �[36;1mGeneratePackage -projectFolder $projectFolder -sdkRootPath $s�[0m …
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[36;1m     | �[31;1m         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[31;1m�[36;1m     | �[31;1mFailed to generate sdk artifact
      cmderr	[Invoke-GenerateAndBuildV2.ps1] �[0m
    • Azure.ResourceManager.AppConfiguration [View full logs]  [Release SDK Changes]
      info	[Changelog]
    ️⚠️ azure-sdk-for-java warning [Detail]
    ️️✔️ azure-sdk-for-js succeeded [Detail] [Expand]
    • ️✔️Succeeded [Logs]Release - Generate from 32e5ec1. SDK Automation 14.0.0
      command	sh .scripts/automation_init.sh ../azure-sdk-for-js_tmp/initInput.json ../azure-sdk-for-js_tmp/initOutput.json
      warn	File azure-sdk-for-js_tmp/initOutput.json not found to read
      command	sh .scripts/automation_generate.sh ../azure-sdk-for-js_tmp/generateInput.json ../azure-sdk-for-js_tmp/generateOutput.json
      cmderr	[automation_generate.sh] [ERROR] Cannot generate changelog because the codes of local and npm may be the same.
    • ️✔️@azure/arm-appconfiguration [View full logs]  [Release SDK Changes]
      info	[Changelog]
      error	breakingChangeTracking is enabled, but version or changelogItem is not found in output.
    ️️✔️ azure-sdk-for-go succeeded [Detail] [Expand]
    • ️✔️Succeeded [Logs]Release - Generate from 32e5ec1. SDK Automation 14.0.0
      command	sh ./eng/scripts/automation_init.sh ../../../../../azure-sdk-for-go_tmp/initInput.json ../../../../../azure-sdk-for-go_tmp/initOutput.json
      command	generator automation-v2 ../../../../../azure-sdk-for-go_tmp/generateInput.json ../../../../../azure-sdk-for-go_tmp/generateOutput.json
    • ️✔️sdk/resourcemanager/appconfiguration/armappconfiguration [View full logs]  [Release SDK Changes]
      info	[Changelog] ### Other Changes
      info	[Changelog]
      info	[Changelog] Total 0 breaking change(s), 0 additive change(s).
    ️⚠️ azure-resource-manager-schemas warning [Detail]
    • ⚠️Warning [Logs]Release - Generate from 32e5ec1. Schema Automation 14.0.0
      command	.sdkauto/initScript.sh ../azure-resource-manager-schemas_tmp/initInput.json ../azure-resource-manager-schemas_tmp/initOutput.json
      cmderr	[initScript.sh]  WARN old lockfile
      cmderr	[initScript.sh] npm WARN old lockfile The package-lock.json file was created with an old version of npm,
      cmderr	[initScript.sh] npm WARN old lockfile so supplemental metadata must be fetched from the registry.
      cmderr	[initScript.sh] npm WARN old lockfile
      cmderr	[initScript.sh] npm WARN old lockfile This is a one-time fix-up, please be patient...
      cmderr	[initScript.sh] npm WARN old lockfile
      warn	File azure-resource-manager-schemas_tmp/initOutput.json not found to read
      command	.sdkauto/generateScript.sh ../azure-resource-manager-schemas_tmp/generateInput.json ../azure-resource-manager-schemas_tmp/generateOutput.json
      warn	No file changes detected after generation
    • ️✔️appconfiguration [View full logs
    ️❌ azure-powershell failed [Detail]
    • Pipeline Framework Failed [Logs]Release - Generate from 32e5ec1. SDK Automation 14.0.0
      command	sh ./tools/SwaggerCI/init.sh ../azure-powershell_tmp/initInput.json ../azure-powershell_tmp/initOutput.json
      command	pwsh ./tools/SwaggerCI/psci.ps1 ../azure-powershell_tmp/generateInput.json ../azure-powershell_tmp/generateOutput.json
      SSL error: syscall failure: Broken pipe
      Error: SSL error: syscall failure: Broken pipe
    • ️✔️Az.appconfiguration.DefaultTag [View full logs
      error	Fatal error: SSL error: syscall failure: Broken pipe
      error	The following packages are still pending:
      error		Az.appconfiguration.DefaultTag
    Posted by Swagger Pipeline | How to fix these errors?

    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented May 1, 2023

    Generated ApiView

    Language Package Name ApiView Link
    Go sdk/resourcemanager/appconfiguration/armappconfiguration https://apiview.dev/Assemblies/Review/688faad4afd54e03b0ec884b970a16a6
    Java azure-resourcemanager-appconfiguration There is no API change compared with the previous version
    JavaScript @azure/arm-appconfiguration https://apiview.dev/Assemblies/Review/65fa015af6cf49c48ecef9d8956126ae

    @@ -821,7 +821,7 @@
    "tags": [
    "KeyValues"
    ],
    "description": "Gets the properties of the specified key-value.",
    "description": "Gets the properties of the specified key-value. NOTE: This operation is intended for use in ARM Template deployments. The data plane API should be used for other interactions with App Configuration key-values.",
    Copy link

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Not sure if people will interpret "other interactions" as "other operations but this one". I know you mean "other scenarios but the ARM template".

    Do you feel if it makes sense to include a link to our data-plane REST API doc?
    https://go.microsoft.com/fwlink/?linkid=2078296

    Copy link
    Member Author

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Do you feel if it makes sense to include a link to our data-plane REST API doc?

    I was a bit on the fence about it. Wasn't sure if it made sense to link to the dataplane REST API spec (in this repo), the link you linked, or SDK link which ultimately this is used to build.

    I'm fine to add the link if you'd like.

    Copy link
    Member Author

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Not sure if people will interpret "other interactions" as "other operations but this one". I know you mean "other scenarios but the ARM template".

    How about

    NOTE: This operation is intended for use in ARM Template deployments. For all other scenarios involving App Configuration key-values the data plane API should be used instead.

    ?

    Copy link

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    NOTE: This operation is intended for use in ARM Template deployments. For all other scenarios involving App Configuration key-values the data plane API should be used instead.

    Love it.

    I was a bit on the fence about it.

    I was just throwing an idea. If a link looks like an outlier to you, I'm okay not having it.

    Copy link
    Member Author

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    I'll omit the link then.

    Updated the wording, thanks !

    @@ -821,7 +821,7 @@
    "tags": [
    "KeyValues"
    ],
    "description": "Gets the properties of the specified key-value.",
    "description": "Gets the properties of the specified key-value. NOTE: This operation is intended for use in ARM Template deployments. For all other scenarios involving App Configuration key-values the data plane API should be used instead.",
    Copy link

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Just want to get your thoughts... How do you feel about mentioning Bicep/Terraform besides of ARM template?

    Copy link
    Member Author

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    my thought is to stick with the most fundamental piece. Kind of how SDK team refers to their JavaScript (and TypeScript) SDK as the JS SDK.

    Copy link

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Sounds good.

    @jimmyca15
    Copy link
    Member Author

    #sign-off

    @raych1 raych1 requested a review from v-jiaodi May 4, 2023 00:22
    @v-jiaodi v-jiaodi added the Approved-OkToMerge <valid label in PR review process>add this label when assignee approve to merge the updates label May 4, 2023
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    Approved-OkToMerge <valid label in PR review process>add this label when assignee approve to merge the updates resource-manager
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    6 participants