微軟的武器kiota：為api生成多語言的SDK

如果你是API 服務提供者，你的客戶，可能使用Python，Java，Golang，你需要為他們寫SDK，怎麼辦呢？手寫？

微軟給了一個解決方案，帶大家一起看看：

歡迎來到基奧塔

Kiota 是一個基于 OpenAPI 的代碼生成器，用于為 HTTP API 建立 SDK。目标是生成一個輕量級、低維護的代碼生成器，它的速度足以作為編譯時工具鍊的一部分運作，但可擴充性足以處理最大的 API。

對于那些想嘗試而不是聽我們為什麼建構它的人，請檢視開始使用 Kiota部分。

目前的 SDK 工具迫使 API 提供者選擇 API 消費者希望如何使用其 API 的粒度。然而，你不可能取悅所有人。一些建構移動應用程式的開發人員非常關心二進制檔案，并希望 SDK 隻包含他們需要的内容。其他建構企業體驗的開發人員不必擔心在十幾個 SDK 中找到哪一個包含他們正在尋找的功能。許多公司開始使用 API 管理網關和門戶将整個組織的 API 整合在一起，并在許多 API 之間提供連貫一緻的體驗。但是，傳統的 SDK 會繼續基于提供 API 的團隊釋出。Kiota 可以靈活地快速輕松地建構我們客戶需要的形狀和大小的 SDK，無論大小。

目标

• 快速且可擴充的源代碼生成器，可簡化 HTTP API 的調用
• 提供對多種語言的支援：C#、Java、Typescript、PHP、Ruby、Go
• 利用 OpenAPI 描述的全部功能
• 輕松實作新語言支援
• 通過建構核心庫僅生成必要的源代碼
• 最小化外部依賴
• 利用 JSON Schema 描述生成基于原語的模型序列化/反序列化代碼
• 僅為 OpenAPI 描述的指定子集啟用代碼生成
• 生成啟用 IDE 自動完成功能的代碼，以幫助發現 API 資源
• 啟用對 HTTP 功能的完全通路權限
• 輕量級、易于安裝的指令行工具
• 提供基于 HTTP 片段生成 SDK 示例用法的能力

非目标

• 用于建立不同 SDK API 形狀的可擴充性模型
• 支援其他 API 描述格式

下面看執行個體

為 Go 建構 SDK

所需工具

• go 1.18+以上版本

目标項目要求

在編譯和運作目标項目之前，您需要對其進行初始化。初始化測試項目後，您需要添加對abstraction、authentication、http、serialization JSON和serialization Text包的引用。

建立目标項目

注意：如果您有一個現有項目，則可以使用現有項目，在這種情況下，您可以跳過以下部分。

在要建立新項目的目錄中執行以下指令。

go mod init getuser
           

添加依賴項

建立一個名為getuser.go的檔案并添加以下代碼。

go get github.com/microsoft/kiota-abstractions-go
go get github.com/microsoft/kiota-http-go
go get github.com/microsoft/kiota-serialization-json-go
go get github.com/microsoft/kiota-serialization-text-go
go get github.com/microsoft/kiota-authentication-azure-go
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
           

隻有第一個包github.com/microsoft/kiota-abstractions-go, 是必需的。其他包提供預設實作，如果您願意，您可以選擇用您自己的實作替換。

生成 SDK

Kiota 從 OpenAPI 文檔生成 SDK。建立一個名為getme.yml的檔案并添加示例 OpenAPI 描述的内容。https://microsoft.github.io/kiota/get-started/reference-openapi.html 這裡提供了一個定義檔案的執行個體。你可以參考它

openapi: 3.0.3
info:
  title: Microsoft Graph get user API
  version: 1.0.0
servers:
  - url: https://graph.microsoft.com/v1.0/
paths:
  /me:
    get:
      responses:
        200:
          description: Success!
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/microsoft.graph.user"
components:
  schemas:
    microsoft.graph.user:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string           

然後，您可以使用 Kiota 指令行工具生成 SDK 類。

kiota -l go -d ../getme.yml -c GraphApiClient -n getuser/client -o ./client
           

建立應用程式注冊

注意：如果您的用戶端将調用受 Microsoft 身份平台（如 Microsoft Graph）保護的 API，則需要執行此步驟。

按照為 Microsoft 身份平台身份驗證注冊應用程式中的說明擷取應用程式 ID（也稱為用戶端 ID）。

建立用戶端應用程式

在項目的根目錄中建立一個名為getuser.go的檔案并添加以下代碼。替換YOUR_CLIENT_ID為您的應用注冊中的用戶端 ID。

package main

import (
  "context"
  "fmt"

  "getuser/client"

  "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
  azure "github.com/microsoft/kiota-authentication-azure-go"
  http "github.com/microsoft/kiota-http-go"
)

func main() {
  clientId := "YOUR_CLIENT_ID"

  // The auth provider will only authorize requests to
  // the allowed hosts, in this case Microsoft Graph
  allowedHosts := []string{"graph.microsoft.com"}
  graphScopes := []string{"User.Read"}

  credential, err := azidentity.NewDeviceCodeCredential(&azidentity.DeviceCodeCredentialOptions{
    ClientID: clientId,
    UserPrompt: func(ctx context.Context, dcm azidentity.DeviceCodeMessage) error {
      fmt.Println(dcm.Message)
      return nil
    },
  })

  if err != nil {
    fmt.Printf("Error creating credential: %v\n", err)
  }

  authProvider, err := azure.NewAzureIdentityAuthenticationProviderWithScopesAndValidHosts(
    credential, graphScopes, allowedHosts)

  if err != nil {
    fmt.Printf("Error creating auth provider: %v\n", err)
  }

  adapter, err := http.NewNetHttpRequestAdapter(authProvider)

  if err != nil {
    fmt.Printf("Error creating request adapter: %v\n", err)
  }

  client := client.NewGraphApiClient(adapter)

  me, err := client.Me().Get(nil)

  if err != nil {
    fmt.Printf("Error getting user: %v\n", err)
  }

  fmt.Printf("Hello %s, your ID is %s\n", *me.GetDisplayName(), *me.GetId())
}
           

筆記：

如果目标 API 不需要任何身份驗證，則可以改用AnonymousAuthenticationProvider。如果目标 API 需要Authorization: Bearer <token>标頭但不依賴于 Microsoft 身份平台，則可以通過從BaseBearerTokenAuthenticationProvider繼承來實作自己的身份驗證提供程式。如果目标 API 需要任何其他形式的身份驗證方案，您可以實作AuthenticationProvider接口。

執行應用程式

當準備好執行應用程式時，在您的項目目錄中執行以下指令。

go run .           

例子是以Azure 為樣本的，可以看到用kiota工具，為你的http接口定義，生成SDK源代碼，然後在你實際項目代碼引入，就可以直接用了。