Azure-sdk-for-net: Search: Handle selected properties for List operations

[heaths]

Many of our List operations for SearchServiceClient accept an optional list of property names, but for .NET this isn't as intuitive since model property names like Name won't actually work (server error): name is required. Additionally, while etag is also not recognized, @odata.etag (theunderlying property name) causes a different server error: that @odata.etag is not allowed in $select or $expand query parameters.

[brjohnstmsft]

An alternative to exposing this parameter on the client would be to have Get[Resource]Names APIs instead. That's the original purpose behind adding $select to those REST APIs in the first place. Those APIs actually run much faster with $select=name because we use a different code path in the service that doesn't retrieve all the metadata, only enumerates the names.

[heaths]

/cc @tg-msft @sima-zhu @xirzec @xiangyan99 @bryevdv

I like that idea. I noticed several properties couldn't even be specified in $select like etags. Anyone have any concerns with just providing Get{Resource}Names methods instead, especially if we split up the clients anyway?

[heaths]

I was thinking about this last night and got to thinking about a compromise between the difficulty in properly maintaining allowed property names, discoverability and understanding of using that, and performance. Instead of Get{Resource}Names and a separate Get{Resource}s, what about Get{Resource}s(bool onlyName = true, ...)? Either should work well for other languages.

I think we should still keep Get{Resource}s because for Key Vault we still get a lot of requests for getting all secrets, for example. There, however, list and get operations were intentionally separated because there are separate list and get permissions. Instead, people have to list, and for each interesting resources get the entire thing, which is everything they just got + the sensitive information like a secret or key.

Though, as long as we end up separating out "sub-clients", having the Get{Resource}Names wouldn't blow up the method count per client anyway. We should still have Get{Resource}s for the reason I mentioned above using Key Vault as an example, though.

[brjohnstmsft]

@heaths A parameter like onlyName would work, although the response would be less convenient to consume than having a dedicated Get...Names API. Choosing between them might come down to which is most discoverable.

[heaths]

Good point. With Get{Resource}Names we could just return a collection of strings. We'll stick with that suggestion as the recommendation then.

[tg-msft]

Is there any way to check how customers are actually using this from telemetry? I think it's fine to offer Get*Names for convenience, but we might still want to support $select if there are scenarios. I'm fine making it less usable though (i.e., not getting fancy with name translation if we're supporting Get*Names for the common case).