Azure Service Fabric JAVA 用戶端 APIAzure Service Fabric Java Client APIs

Service Fabric 用戶端 API 允許在 Azure、內部佈署、本機開發機器或其他雲端上,部署及管理微服務型應用程式和 Service Fabric 叢集內的容器。Service Fabric client APIs allows deploying and managing microservices based applications and containers in a Service Fabric cluster on Azure, on-premises, on local development machine or in other cloud. 本文說明如何在 Service Fabric client REST API 上產生及使用 Service Fabric JAVA 用戶端 APIThis article describes how to generate and use Service Fabric Java client APIs on top of the Service Fabric client REST APIs

使用 AutoRest 產生用戶端程式碼Generate the client code using AutoRest

AutoRest 工具可產生用戶端程式庫以存取 RESTful Web 服務。AutoRest is a tool that generates client libraries for accessing RESTful web services. 輸入 AutoRest 的是一種規格,用以描述使用 OpenAPI 規格格式的 REST API。Input to AutoRest is a specification that describes the REST API using the OpenAPI Specification format. Service Fabric 用戶端 REST API 會遵循此規格。Service Fabric client REST APIs follow this specification .

請按照下述步驟,使用 AutoRest 工具產生 Service Fabric JAVA 用戶端程式碼。Follow the steps mentioned below to generate Service Fabric Java client code using the AutoRest tool.

  1. 在電腦上安裝 nodejs 和 NPMInstall nodejs and NPM on your machine

    如果您是使用 Linux:If you are using Linux then:

    sudo apt-get install npm
    sudo apt install nodejs
    

    如果您是使用 Mac OS X:If you are using Mac OS X then:

    brew install node
    
  2. 使用 NPM 安裝 AutoRest。Install AutoRest using NPM.

    npm install -g autorest
    
  3. 在本機電腦中派生及複製 azure-rest-api-specs 存放庫,並從您電腦的終端機移動至複製的位置。Fork and clone azure-rest-api-specs repository in your local machine and go to the cloned location from the terminal of your machine.

  4. 請前往您複製存放庫中的下述位置。Go to the location mentioned below in your cloned repo.

    cd specification\servicefabric\data-plane\Microsoft.ServiceFabric\stable\6.0
    

    注意

    如果您的叢集版本不是 6.0.*,請前往穩定資料夾中的正確目錄。If your cluster version is not 6.0.* then go to the appropriate directory in the stable folder.

  5. 執行下列 autorest 命令以產生 java 用戶端程式碼。Run the following autorest command to generate the java client code.

    autorest --input-file= servicefabric.json --java --output-folder=[output-folder-name] --namespace=[namespace-of-generated-client]
    

    下有示範 autorest 使用方式的範例。Below is an example demonstrating the usage of autorest.

    autorest --input-file=servicefabric.json --java --output-folder=java-rest-api-code --namespace=servicefabricrest
    

    下列命令會採用 servicefabric.json 規格檔案作為輸入,並在 java-rest-api- code 資料夾中產生 java 用戶端程式碼,並在 servicefabricrest 命名空間中括住程式碼。The following command takes servicefabric.json specification file as input and generates java client code in java-rest-api- code folder and encloses the code in servicefabricrest namespace. 在此步驟之後,會發現 java-rest-api-code 資料夾產生了兩個資料夾 modelsimplementation,以及 ServiceFabricClientAPIs.javapackage-info.java 兩個檔案。After this step you would find two folders models, implementation and two files ServiceFabricClientAPIs.java and package-info.java generated in the java-rest-api-code folder.

在專案中加入並使用產生的客戶端Include and use the generated client in your project

  1. 將產生的程式碼正確地加入專案中。Add the generated code appropriately into your project. 建議使用所產生的程式碼來建立程式庫,並將此程式庫加入您的專案。We recommend that you create a library using the generated code and include this library in your project.

  2. 如果您要建立程式庫,請將下列相依性加入您程式庫的專案中。If you are creating a library then include the following dependency in your library's project. 如果所用的方法不同,請加入合適的相依性。If you are following a different approach then include the dependency appropriately.

        GroupId:  com.microsoft.rest
        Artifactid: client-runtime
        Version: 1.2.1
    

    舉例而言,如果使用 Maven 建立系統,請將下列內容加入您的 pom.xml 檔案:For example, if you are using Maven build system include the following in your pom.xml file:

        <dependency>
          <groupId>com.microsoft.rest</groupId>
          <artifactId>client-runtime</artifactId>
          <version>1.2.1</version>
        </dependency>
    
  3. 使用下列程式碼建立 RestClient:Create a RestClient using the following code:

        RestClient simpleClient = new RestClient.Builder()
            .withBaseUrl("http://<cluster-ip or name:port>")
            .withResponseBuilderFactory(new ServiceResponseBuilder.Factory())
            .withSerializerAdapter(new JacksonAdapter())
            .build();
        ServiceFabricClientAPIs client = new ServiceFabricClientAPIsImpl(simpleClient);
    
  4. 使用用戶端物件,並視需要進行適當的呼叫。Use the client object and make the appropriate calls as required. 以下是示範用戶端物件使用方式的一些範例。Here are some examples which demonstrate the usage of client object. 假定在使用下列 API 之前,已建立應用程式封裝,並上傳到映像存放區。We assume that the application package is built and uploaded into image store before using the below API's.

    • 佈建應用程式Provision an application

          ApplicationTypeImageStorePath imageStorePath = new ApplicationTypeImageStorePath();
          imageStorePath.withApplicationTypeBuildPath("<application-path-in-image-store>");
          client.provisionApplicationType(imageStorePath);
      
    • 建立應用程式Create an application

          ApplicationDescription applicationDescription = new ApplicationDescription();
          applicationDescription.withName("<application-uri>");
          applicationDescription.withTypeName("<application-type>");
          applicationDescription.withTypeVersion("<application-version>");
          client.createApplication(applicationDescription);
      

了解產生的程式碼Understanding the generated code

您會發現每一種 API 有四個實作的多載。For every API you will find four overloads of implementation. 如果有選擇性參數,則會發現另外四個包含選擇性參數的變異。If there are optional parameters then you would find four more variations including those optional parameters. 例如,請思考 API removeReplicaFor example consider the API removeReplica.

  1. public void removeReplica(String nodeName, UUID partitionId, String replicaId, Boolean forceRemove, Long timeout)public void removeReplica(String nodeName, UUID partitionId, String replicaId, Boolean forceRemove, Long timeout)
    • 這是 removeReplica API 呼叫的同步變數This is the synchronous variant of the removeReplica API call
  2. public ServiceFuture<Void> removeReplicaAsync(String nodeName, UUID partitionId, String replicaId, Boolean forceRemove, Long timeout, final ServiceCallback<Void> serviceCallback)public ServiceFuture<Void> removeReplicaAsync(String nodeName, UUID partitionId, String replicaId, Boolean forceRemove, Long timeout, final ServiceCallback<Void> serviceCallback)
    • 如果您想要使用未來式非同步程式設計並使用回呼,可使用此 API 呼叫的變數This variant of API call can be used if you want to use future based asynchronous programming and use callbacks
  3. public Observable<Void> removeReplicaAsync(String nodeName, UUID partitionId, String replicaId)public Observable<Void> removeReplicaAsync(String nodeName, UUID partitionId, String replicaId)
    • 如果您想要使用回應式非同步程式設計,可使用此 API 呼叫的變數This variant of API call can be used if you want to use reactive asynchronous programming
  4. 公用可觀察 <ServiceResponse<Void>> removeReplicaWithServiceResponseAsync (字串 nodeName、UUID partitionId、字串 replicaId)public Observable<ServiceResponse<Void>> removeReplicaWithServiceResponseAsync(String nodeName, UUID partitionId, String replicaId)
    • 如果您想要使用回應式非同步程式設計,並處理 RAW REST 回應,可使用此 API 呼叫的變數This variant of API call can be used if you want to use reactive asynchronous programming and deal with RAW rest response

下一步Next steps