{AD} az ad app permission add: Refine error message for incorrect --api-permissions

[jiasli]

Related command
az ad app permission add

Description

Refine the error message per #10718, #15598, #16868, #17057, #18185, #18408, #22826

The correct usage of --api-permissions from az ad app permission add is {id}={type}. The help message and examples are pretty clear about this. They even show how to retrieve {id} and {type}.

> az ad app permission add --help

Command
    az ad app permission add : Add an API permission.
        Invoking "az ad app permission grant" is needed to activate it.

        To get available permissions of the resource app, run `az ad sp show --id <resource-appId>`.
        For example, to get available permissions for Microsoft Graph API, run `az ad sp show --id
        00000003-0000-0000-c000-000000000000`. Application permissions under the `appRoles` property
        correspond to `Role` in --api-permissions. Delegated permissions under the
        `oauth2Permissions` property correspond to `Scope` in --api-permissions.

Arguments
    --api             [Required] : RequiredResourceAccess.resourceAppId - The unique identifier for
                                   the resource that the application requires access to. This should
                                   be equal to the appId declared on the target resource
                                   application.
    --api-permissions [Required] : Space-separated list of {id}={type}. {id} is resourceAccess.id -
                                   The unique identifier for one of the oauth2PermissionScopes or
                                   appRole instances that the resource application exposes. {type}
                                   is resourceAccess.type - Specifies whether the id property
                                   references an oauth2PermissionScopes or an appRole. The possible
                                   values are: Scope (for OAuth 2.0 permission scopes) or Role (for
                                   app roles).
    --id              [Required] : Identifier uri, application id, or object id.

...

Examples
    Add Microsoft Graph delegated permission User.Read (Sign in and read user profile).
        az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-
        permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

    Add Microsoft Graph application permission Application.ReadWrite.All (Read and write all
    applications).
        az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-
        permissions 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9=Role

When --api-permissions is provided incorrectly, the command az ad app permission add fails with an ugly error:

The command failed with an unexpected error. Here is the traceback:
not enough values to unpack (expected 2, got 1)
Traceback (most recent call last):
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/knack/cli.py", line 231, in invoke
    cmd_result = self.invocation.execute(args)
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/__init__.py", line 663, in execute
    raise ex
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/__init__.py", line 726, in _run_jobs_serially
    results.append(self._run_job(expanded_arg, cmd_copy))
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/__init__.py", line 718, in _run_job
    return cmd_copy.exception_handler(ex)
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/command_modules/role/commands.py", line 54, in graph_err_handler
    raise ex
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/__init__.py", line 697, in _run_job
    result = cmd_copy(params)
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/__init__.py", line 333, in __call__
    return self.handler(*args, **kwargs)
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/core/commands/command_operation.py", line 121, in handler
    return op(**command_args)
  File "/usr/local/Cellar/azure-cli/2.37.0/libexec/lib/python3.10/site-packages/azure/cli/command_modules/role/custom.py", line 859, in add_permission
    access_id, access_type = e.split('=')
ValueError: not enough values to unpack (expected 2, got 1)

Now this command gives a better error message:

> az ad app permission add --id 233dd73b-72e3-424a-9367-7588d957267e --api 00000003-0000-0000-c000-000000000000 --api-permissions 1bfefb4e-e0b5-418b-a88f-73c46d2cc8e9
Usage error: Please provide both permission id and type, such as `--api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope`

[jiasli]

We delay the application resolution so that the above check fails quicker.

[yonzhan]

Role