Skip to content

Latest commit

 

History

History
94 lines (61 loc) · 5.36 KB

dataplane-customization.md

File metadata and controls

94 lines (61 loc) · 5.36 KB
Raw

Customization on Data-Plane Client

Generate Data-Plane Client

Follow Quickstart to generate the Data-Plane Client from OpenAPI specs.

Change Client Behavior

Support Azure Active Directory Authentication

See Authentication in SDK.

It is advised to update OpenAPI specs with security: AADToken. And then re-generate the SDK.

If one does not wish to change the specs, add following configure to README_SPEC.md, and re-generate the SDK.

security: AADToken
security-scopes: https://cognitiveservices.azure.com/.default

Here is an example of the modification of README_SPEC.md and the resulted code changes. Note that a new method credential(TokenCredential tokenCredential) is generated in builder class.

Support Customized Authentication

Usually security: AzureKey can provide implementation of API key authentication.

For more complex API key authentication, one can customize the builder class.

Here is an example of the modification of builder to support subscription key and API key.

  1. Create MetricsAdvisorKeys and MetricsAdvisorKeyCredential class in models package.
  2. Modify MetricsAdvisorClientBuilder to accept MetricsAdvisorKeyCredential from user, and then pass the keys in it to HTTP pipeline.

Note that the Generated annotation on createHttpPipeline() is removed, as we customized this method. This ensures that future code generate will not override this customized method.

Change Operation Behavior

Generated client methods accept RequestOptions for request parameters. For frequently invoked methods, one can customize them for better user-experience.

Here is an example of the modification of client to support options for client methods.

  1. Create ListDataFeedFilter and ListDataFeedOptions class in models package.
  2. Modify MetricsAdvisorAsyncClient and MetricsAdvisorClient to provide overloaded listDataFeeds method that takes ListDataFeedOptions options.
  3. Convert options from ListDataFeedOptions to RequestOptions in listDataFeeds method.

Note that the conversion only happen once in package private MetricsAdvisorAsyncClient.listDataFeeds(ListDataFeedOptions, Context) method, which is invoked by all added listDataFeeds methods.

Add Model

Generated client methods accept and produce BinaryData for request payload and response body. For frequently invoked methods, one can customize them for better user-experience.

Model as Response Body

Here is an example of the modification of client to support DataFeedDetail as response of paged operation.

  1. Create DataFeedDetail class and all related classed in models package.
  2. Modify MetricsAdvisorAsyncClient and MetricsAdvisorClient to provide overloaded listDataFeeds method that produce paged response of DataFeedDetail. (as these are already customized method, in example we only modify them in place)
  3. BinaryData.toObject(Class<T>) convert BinaryData to DataFeedDetail.
  4. Utility method mapPage(PagedFlux<T> pagedFlux, Function<T, S> mapper) is provided to convert PagedFlux.
  5. Convert response of PagedFlux<BinaryData> to PagedFlux<DataFeedDetail> in listDataFeeds method.

Note that the conversion only happen once in package private MetricsAdvisorAsyncClient.listDataFeeds(ListDataFeedOptions, Context) method, which is invoked by all added listDataFeeds methods.

Model as Request Payload

Here is an example of the modification of client to support DataFeedDetail as request payload.

  1. Create DataFeedDetail class and all related classed in models package.
  2. Modify MetricsAdvisorAsyncClient and MetricsAdvisorClient to provide overloaded createDataFeed method that accept DataFeedDetail.
  3. BinaryData.fromObject(Class<T>) convert DataFeedDetail to BinaryData.

Note that the conversion only happen once in package private createDataFeed(DataFeedDetail dataFeed, Context context) method, which is invoked by all added createDataFeed methods.

In this special scenario, service only return a "Location" header of the resource URL of the created data feed. For better user-experience, SDK send another GET request to retrieve the detail of the created data feed, following the resource URL.

Java Code Considerations

models Package

When one create models package to house the model classes, one need to consider:

  1. Add a package-info.java in models package.
  2. Modify module-info.java to expose it to user, and optionally open it to JSON serialization. See Java Modules.

A typical section in module-info.java:

exports com.azure.ai.metricsadvisor.models;

opens com.azure.ai.metricsadvisor.models to
    com.azure.core,
    com.fasterxml.jackson.databind;