準備外掛程式程式碼

您為 Service Extensions 外掛程式建立的自訂程式碼必須先封裝並上傳至 Artifact Registry，其他服務才能存取。本頁說明如何建立外掛程式碼、封裝程式碼，以及將程式碼上傳至 Artifact Registry 存放區。

這項功能為 Media CDN 的預先發布版。

如要瞭解 Service Extensions，請參閱「Service Extensions 總覽」。

開始之前，請先詳閱外掛程式程式碼撰寫最佳做法。

如需更多範例，請參閱「外掛程式的程式碼範例」。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Network Services, Network Actions, Artifact Registry, Cloud Build, Cloud Logging, and Cloud Monitoring APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. 安裝 Google Cloud CLI。

  6. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  7. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Network Services, Network Actions, Artifact Registry, Cloud Build, Cloud Logging, and Cloud Monitoring APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  11. 安裝 Google Cloud CLI。

  12. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  13. 執行下列指令，初始化 gcloud CLI：

    gcloud init

設定工具鍊

C++

開發人員可透過 Proxy-Wasm C++ SDK，使用 C++ 為 Service Extensions 實作 WebAssembly (Wasm) 外掛程式。這個 SDK 使用 C++ WebAssembly 工具鍊 Emscripten，以及其他程式庫，例如 protobuf 和 (選擇性) Abseil。

由於建構以 C++ 編寫的外掛程式時，需要特定版本的工具和程式庫，因此建議使用 Proxy-Wasm C++ SDK 提供的 Docker 映像檔。本頁的 C++ 指示使用 Docker 方法。如要建構 C++ 外掛程式，但不想使用 Docker，請參閱 Proxy-Wasm C++ SDK 說明文件。

  1. 如果尚未安裝 Docker，請安裝。Cloud Shell 內含 Docker，這是 Google Cloud 互動式殼層環境。

  2. 下載 Proxy-Wasm C++ SDK 副本。最簡單的方法是複製 Git 存放區：

    git clone https://github.com/proxy-wasm/proxy-wasm-cpp-sdk.git

  3. 從 SDK 提供的 Dockerfile 建構 Proxy-Wasm C++ SDK Docker 映像檔：

    cd proxy-wasm-cpp-sdk
docker build -t wasmsdk:v3 -f Dockerfile-sdk .

    指令完成建構 SDK 程式庫和依附元件後，產生的 Docker 映像檔會與指定的標記建立關聯，在本例中為 wasmsdk:v3。

Go

Proxy-Wasm Go SDK 提供全功能 Go SDK。Go 效能良好，且支援以純 Go 語言編寫的第三方程式庫。

安裝 Go 工具鍊 v1.24.0。

Rust

Service Extensions 的自訂功能是透過 WebAssembly 和 Proxy-Wasm 提供。WebAssembly 支援多種程式設計語言。Google 建議使用 Rust，因為 Rust 支援 WebAssembly，且 Proxy-Wasm 提供功能齊全的 Rust SDK。Rust 的效能良好，且型別安全機制十分強大。

  1. 安裝 Rust 工具鍊。

    安裝程序完成後，請按照控制台上列印的指示操作，完成設定程序。

  2. 在 Rust 工具鍊中新增 Wasm 支援：

    rustup target add wasm32-wasip1

建立外掛程式套件

C++

  1. 建立與 proxy-wasm-cpp-sdk 分開的新目錄：

    mkdir myproject

  2. 在目錄中建立 Makefile，並加入以下內容：

    # Express any dependencies
PROTOBUF=     # full / lite / none
WASM_DEPS=    # absl_base re2 ...

# Include the SDK Makefile
PROXY_WASM_CPP_SDK=/sdk
include ${PROXY_WASM_CPP_SDK}/Makefile

  3. 在同一個目錄中，為外掛程式新增 C++ 來源檔案。C++ 來源檔案的名稱必須與 Makefile 目標的 Wasm 檔案相符，並將 .wasm 後置字串替換為 .cc。在本範例中，來源檔案必須命名為 myproject.cc。

  4. 將外掛程式程式碼新增至來源檔案。

    下列範例原始碼是外掛程式，可重新編寫要求主機，並發出回應標頭：

    #include "proxy_wasm_intrinsics.h"

class MyHttpContext : public Context {
 public:
  explicit MyHttpContext(uint32_t id, RootContext* root) : Context(id, root) {}

  FilterHeadersStatus onRequestHeaders(uint32_t headers,
                                       bool end_of_stream) override {
    LOG_INFO("onRequestHeaders: hello from wasm");

    // Route Extension example: host rewrite
    if (replaceRequestHeader(":authority", "service-extensions.com") != WasmResult::Ok) {
      LOG_ERROR("Failed to replace :authority header");
    }
    if (replaceRequestHeader(":path", "/") != WasmResult::Ok) {
      LOG_ERROR("Failed to replace :path header");
    }
    return FilterHeadersStatus::Continue;
  }

  FilterHeadersStatus onResponseHeaders(uint32_t headers,
                                        bool end_of_stream) override {
    LOG_INFO("onResponseHeaders: hello from wasm");

    // Traffic Extension example: add response header
    if (addResponseHeader("hello", "service-extensions") != WasmResult::Ok) {
      LOG_ERROR("Failed to add response header");
    }
    return FilterHeadersStatus::Continue;
  }
};

static RegisterContextFactory register_StaticContext(
    CONTEXT_FACTORY(MyHttpContext), ROOT_FACTORY(RootContext));

    onRequestHeaders 方法是 Service Extensions 叫用的回呼。

Go

  1. 為外掛程式建立新目錄：

    mkdir go-plugin

  2. 在目錄中，使用 Go 工具建立 go.mod 檔案：

    go mod init go-plugin

  3. 在同一個目錄中，建立名為 main.go 的來源檔案，並將外掛程式程式碼新增至該檔案。

    下列範例原始碼是外掛程式，可重新編寫要求主機，並發出回應標頭：

    package main

import (
	"fmt"

	"github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm"
	"github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm/types"
)

func main() {}
func init() {
	proxywasm.SetVMContext(&vmContext{})
}

type vmContext struct {
	types.DefaultVMContext
}

type pluginContext struct {
	types.DefaultPluginContext
}

type httpContext struct {
	types.DefaultHttpContext
}

func (*vmContext) NewPluginContext(contextID uint32) types.PluginContext {
	return &pluginContext{}
}

func (*pluginContext) NewHttpContext(uint32) types.HttpContext {
	return &httpContext{}
}

func (ctx *httpContext) OnHttpRequestHeaders(numHeaders int, endOfStream bool) types.Action {
	defer func() {
		err := recover()
		if err != nil {
			proxywasm.SendHttpResponse(500, [][2]string{}, []byte(fmt.Sprintf("%v", err)), 0)
		}
	}()
	proxywasm.LogInfof("onRequestHeaders: hello from wasm")

	// Route Extension example: host rewrite
	err := proxywasm.ReplaceHttpRequestHeader(":authority", "service-extensions.com")
	if err != nil {
		panic(err)
	}
	err = proxywasm.ReplaceHttpRequestHeader(":path", "/")
	if err != nil {
		panic(err)
	}
	return types.ActionContinue
}

func (ctx *httpContext) OnHttpResponseHeaders(numHeaders int, endOfStream bool) types.Action {
	defer func() {
		err := recover()
		if err != nil {
			proxywasm.SendHttpResponse(500, [][2]string{}, []byte(fmt.Sprintf("%v", err)), 0)
		}
	}()
	proxywasm.LogInfof("onResponseHeaders: hello from wasm")

	// Traffic Extension example: add response header
	err := proxywasm.AddHttpResponseHeader("hello", "service-extensions")
	if err != nil {
		panic(err)
	}
	return types.ActionContinue
}

    OnHttpRequestHeaders 方法是 Service Extensions 叫用的回呼。

  4. 如要下載及釘選程式庫依附元件，請執行 go mod tidy：

    go mod tidy

Rust

  1. 使用 Rust 的套件管理工具 Cargo 的 cargo new 指令，建立 Rust 套件目錄：

    cargo new --lib my-wasm-plugin

    這個指令會建立一個目錄，其中包含 cargo.toml 檔案 (可更新以說明如何建構 Rust 套件) 和 src 目錄 (用於儲存外掛程式碼)。

  2. 更新 cargo.toml 檔案，指定建構套件所需的參數：

    [package]
name = "my-wasm-plugin"
version = "0.1.0"
edition = "2021"

  3. 如要將 Proxy-Wasm Rust SDK 和記錄支援功能註冊為依附元件，請新增 dependencies 區段。例如：

    [dependencies]
proxy-wasm = "0.2"
log = "0.4"

  4. 如要建構外掛程式所需的動態程式庫，請新增 lib 區段。 例如：

    [lib]
crate-type = ["cdylib"]

  5. 如要縮減編譯外掛程式的大小，請新增 profile.release 區段。例如：

    [profile.release]
lto = true
opt-level = 3
codegen-units = 1
panic = "abort"
strip = "debuginfo"

  6. 將外掛程式程式碼新增至 src 目錄中的 lib.rs 檔案。

    下列範例原始碼是外掛程式，可重新編寫要求主機，並發出回應標頭：

    use log::info;
use proxy_wasm::traits::*;
use proxy_wasm::types::*;

proxy_wasm::main! { {
    proxy_wasm::set_log_level(LogLevel::Trace);
    proxy_wasm::set_http_context(|_, _| -> Box<dyn HttpContext> { Box::new(MyHttpContext) });
} }

struct MyHttpContext;

impl Context for MyHttpContext {}

impl HttpContext for MyHttpContext {
    fn on_http_request_headers(&mut self, _: usize, _: bool) -> Action {
        info!("onRequestHeaders: hello from wasm");

        // Route extension example: host rewrite
        self.set_http_request_header(":authority", Some("service-extensions.com"));
        self.set_http_request_header(":path", Some("/"));
        return Action::Continue;
    }

    fn on_http_response_headers(&mut self, _: usize, _: bool) -> Action {
        info!("onResponseHeaders: hello from wasm");

        // Traffic extension example: add response header
        self.add_http_response_header("hello", "service-extensions");
        return Action::Continue;
    }
}

    on_http_request_headers 方法是 Service Extensions 叫用的回呼。

編譯外掛程式

C++

如要編譯外掛程式，請在 Makefile 和 C++ 外掛程式來源檔案所在的目錄中執行下列指令：

docker run -v $PWD:/work -w /work wasmsdk:v3 /build_wasm.sh myproject.wasm

這個指令會將目前目錄對應至 Docker 映像檔中的 work 目錄，然後執行 Docker 映像檔提供的 build_wasm.sh 指令碼，建構外掛程式程式碼。編譯作業順利完成後，系統會在目前目錄中建立 myproject.wasm 檔案，其中包含編譯後的 Wasm 位元組碼。

首次使用 Docker 映像檔編譯外掛程式碼時，Emscripten 會產生標準程式庫。如要將這些項目快取到 Docker 映像檔中，以免每次都必須重新產生，請在首次成功編譯後，使用標準程式庫提交映像檔：

docker commit `docker ps -l | grep wasmsdk:v3 | awk '{print $1}'` wasmsdk:v3

如要進一步瞭解如何建構 C++ 外掛程式，請參閱 Proxy-Wasm C++ SDK 說明文件。

Go

如要編譯外掛程式程式碼，請執行 go build 指令：

env GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go

編譯成功後，目前目錄中會建立 main.wasm 檔案。

Rust

如要編譯外掛程式程式碼，請執行 cargo build 指令：

cargo build --release --target wasm32-wasip1

建構成功完成後，畫面上會顯示 Finished release [optimized] target(s) 訊息。如果您熟悉 Envoy，可以載入 Envoy 中的外掛程式並驗證其行為。

將編譯的外掛程式程式碼上傳至 Artifact Registry

將編譯後的外掛程式碼上傳至 Artifact Registry 存放區，以便 Google Cloud 服務存取。

如果搭配全域負載平衡器使用 Service Extensions，請使用多區域 us 位置的存放區。如果您使用區域負載平衡器，請使用相同區域或同一洲多區域位置的存放區。

將外掛程式附加至全域負載平衡器時，Service Extensions 會將 Wasm 模組從 Artifact Registry 存放區複製到全球各地的自有儲存空間。因此，存放區的位置不會影響傳送至負載平衡器的要求延遲時間。如果是區域性負載平衡器，外掛程式會複製到與負載平衡器位於相同區域的位置。

Service Extensions 外掛程式可以上傳至 Artifact Registry 通用或 Docker 存放區。

如要以更直接的方式管理獨立二進位檔，建議您使用一般存放區儲存 Wasm 檔案。這項功能為預先發布版。

一般存放區

  1. 建立本機 package/ 目錄，並將可發布的外掛程式模組複製到該目錄。外掛程式構件必須命名為 plugin.wasm。以下範例指令會複製 Rust 建構的外掛程式構件：

    mkdir -p package && cp -f target/wasm32-wasip1/release/my_wasm_plugin.wasm package/plugin.wasm

  2. 建立 Artifact Registry 存放區，並將 --repository-format 設為 generic。

  3. 確認您具備存放區的必要權限。

  4. 如要將 Wasm 模組以一般構件的形式上傳至存放區，請使用 gcloud artifacts generic upload 指令。

    gcloud artifacts generic upload \
    --project=PROJECT_ID \
    --location=LOCATION \
    --repository=REPOSITORY \
    --source=package/plugin.wasm \
    --package=PACKAGE \
    --version=VERSION

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID
    • LOCATION：存放區的區域或多區域位置
    • REPOSITORY：要上傳 Wasm 模組的存放區名稱
    • PACKAGE：檔案的套件名稱
    • VERSION：Wasm 模組版本

    上傳完成後，請記下一般構件的名稱 (如 name 標籤所述)，例如以下範例中的 add_header_plugin:v4。建立外掛程式或外掛程式版本時，請指定這個名稱。

    Uploading file: plugin.wasm...done.
'@type': type.googleapis.com/google.devtools.artifactregistry.v1.GenericArtifact
createTime: '2025-06-16T11:02:25.080248Z'
name: projects/my-project/locations/us/repositories/my-generic-repo/genericArtifacts/add_header_plugin:v4
updateTime: '2025-06-16T11:02:25.080248Z'
version: v4

  5. 如要確認構件已成功上傳至 Artifact Registry，請執行 gcloud artifacts files list 指令，並確認清單中有名為 PACKAGE:VERSION:plugin.wasm 的檔案。

     gcloud artifacts files list \
     --project=PROJECT_ID \
     --location=LOCATION \
     --repository=REPOSITORY

Docker 存放區

  1. 建立 Artifact Registry 存放區，並將 --repository-format 設為 docker。

  2. 確認您具備存放區的必要權限。

  3. 建立本機 package/ 目錄，然後將可發布的外掛程式構件複製到該目錄。以下範例會複製 Rust 建構的外掛程式構件：

    mkdir -p package && cp -f target/wasm32-wasip1/release/my_wasm_plugin.wasm package/plugin.wasm

  4. 使用以下內容建立 package/Dockerfile 檔案：

    FROM scratch
COPY plugin.wasm plugin.wasm

  5. 使用 Cloud Build 或 Docker 將外掛程式程式碼封裝。

    Cloud Build

    1. 建立 package/cloudbuild.yaml build config 檔案，並加入以下內容：

      steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: [ 'build', '--no-cache', '--platform', 'wasm',
          '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:IMAGE_TAG', '.' ]
images: [ 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:IMAGE_TAG' ]

      外掛程式的儲存路徑必須採用下列格式：

      LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:IMAGE_TAG

      更改下列內容：

      • LOCATION：存放區的區域或多區域位置
      • PROJECT_ID：您的 Google Cloud 控制台專案 ID
      • REPOSITORY：您打算儲存映像檔的存放區名稱
      • IMAGE：存放區中的容器映像檔名稱，例如 us-docker.pkg.dev/my-project/my-repo/my-wasm-plugin
      • IMAGE_TAG：要指派給容器的圖片標記，例如 production

    2. 觸發作業，建構外掛程式容器並上傳至 Artifact Registry：

      gcloud builds submit --config package/cloudbuild.yaml package/

    Docker

    1. 如果尚未安裝 Docker，請安裝。Cloud Shell 內含 Docker，這是 Google Cloud 互動式殼層環境。

    2. 設定 Docker 向 Artifact Registry 進行驗證。 例如：

      gcloud auth login
gcloud auth configure-docker LOCATION-docker.pkg.dev
gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev

    3. 建構容器映像檔：

      docker build --no-cache --platform wasm -t my-wasm-plugin package/

    4. 如要使用存放區映像檔名稱標記本機映像檔，請使用映像檔標記：

      docker tag my-wasm-plugin LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:IMAGE_TAG

      更改下列內容：

      • LOCATION：存放區的區域或多區域位置
      • PROJECT_ID：您的 Google Cloud 控制台專案 ID
      • REPOSITORY：您打算儲存映像檔的存放區名稱
      • IMAGE：存放區中的容器映像檔名稱，例如 us-docker.pkg.dev/my-project/my-repo/my-wasm-plugin。
      • IMAGE_TAG：要指派給容器的圖片標記，例如 production

    5. 將加上標記的容器映像檔上傳至 Artifact Registry。

      docker push LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:IMAGE_TAG

  6. 如要確認映像檔已成功上傳至 Artifact Registry，請執行 gcloud artifacts docker images list 指令。

    gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE \
    --include-tags

準備及上傳設定檔

外掛程式可以選擇性接收設定資料，這可能會影響外掛程式在執行階段的行為。設定資料可以是文字或二進位格式，也可以是外掛程式接受的任何格式。如果設定資料量很大，您可能需要將設定檔上傳至 Artifact Registry。

編寫外掛程式程式碼，讀取設定資料

C++

設定資料會傳遞至根內容物件的 onConfigure 方法，這個物件會在外掛程式啟動時例項化一次，並在主機外掛程式的 Wasm 執行階段生命週期內保持啟用狀態。根內容物件是 RootContext 類別的執行個體，或是 RootContext 的子類別。

外掛程式程式碼可透過 RegisterContextFactory 值，控制用於根環境的類別。舉例來說，下列外掛程式碼會將 MyRootContext 和 MyHttpContext 註冊為用於根層級和串流內容執行個體的類別。然後從外掛程式設定資料讀取密鑰值，串流內容執行個體可透過根內容物件存取該值。

#include <string>
#include <string_view>

#include "proxy_wasm_intrinsics.h"

class MyRootContext : public RootContext {
 public:
  explicit MyRootContext(uint32_t id, std::string_view root_id)
      : RootContext(id, root_id) {}

  bool onConfigure(size_t config_len) override {
    auto buffer = getBufferBytes(WasmBufferType::PluginConfiguration, 0, config_len);
    if (!buffer) {
      LOG_ERROR("Failed to retrieve plugin configuration");
      return false;
    }
    secret_ = buffer->toString();
    return true;
  }

  const std::string& secret() const { return secret_; }

 private:
  std::string secret_;
};

class MyHttpContext : public Context {
 public:
  explicit MyHttpContext(uint32_t id, RootContext* root)
      : Context(id, root),
        secret_(static_cast<MyRootContext*>(root)->secret()) {}

  FilterHeadersStatus onRequestHeaders(uint32_t headers,
                                       bool end_of_stream) override {
    // Use secret here...
    LOG_INFO("secret: " + secret_);
    return FilterHeadersStatus::Continue;
  }

 private:
  const std::string& secret_;
};

static RegisterContextFactory register_MyHttpContext(
    CONTEXT_FACTORY(MyHttpContext), ROOT_FACTORY(MyRootContext));

Go

執行 OnPluginStart 時會讀取設定資料，這是執行階段在外掛程式啟動時，於 PluginContext struct 上執行一次的方法接收器。在主機外掛程式的 Wasm 執行階段生命週期內，設定資料不會變更。PluginContext 可用於執行初始化邏輯，並在多個要求中維護狀態。

外掛程式程式碼可以在 VMContext 上實作 NewPluginContext 方法，藉此例項化 PluginContext，進而控制 PluginContext 使用的內容。PluginContext 接著會例項化 HttpContext 情境。

舉例來說，下列外掛程式碼會註冊 VMContext，該程式碼會例項化 PluginContext，也就是負責讀取設定資料並視需要例項化 HttpContext 環境的內容。PluginContext 會從外掛程式設定資料讀取密鑰值，並將該值儲存在 PluginContext 環境中，然後在 NewHttpContext 中傳遞至 HttpContext。

package main

import (
	"fmt"

	"github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm"
	"github.com/proxy-wasm/proxy-wasm-go-sdk/proxywasm/types"
)

func main() {}
func init() {
	proxywasm.SetVMContext(&vmContext{})
}

type vmContext struct {
	types.DefaultVMContext
}

type pluginContext struct {
	types.DefaultPluginContext
	secret string
}

type httpContext struct {
	types.DefaultHttpContext
	pluginContext *pluginContext
}

func (*vmContext) NewPluginContext(contextID uint32) types.PluginContext {
	return &pluginContext{}
}

func (ctx *pluginContext) OnPluginStart(int) types.OnPluginStartStatus {
	config, err := proxywasm.GetPluginConfiguration()
	if err != nil {
		proxywasm.LogErrorf("Error reading the configuration: %v", err)
		return types.OnPluginStartStatusFailed
	}
	if config == nil {
		proxywasm.LogError("Configuration is nil")
		return types.OnPluginStartStatusFailed
	}
	ctx.secret = string(config)
	return types.OnPluginStartStatusOK
}

func (ctx *pluginContext) NewHttpContext(uint32) types.HttpContext {
	return &httpContext{pluginContext: ctx}
}

func (ctx *pluginContext) Secret() string {
	return ctx.secret
}

func (ctx *httpContext) OnHttpRequestHeaders(numHeaders int, endOfStream bool) types.Action {
	defer func() {
		err := recover()
		if err != nil {
			proxywasm.SendHttpResponse(500, [][2]string{}, []byte(fmt.Sprintf("%v", err)), 0)
		}
	}()
	// Use secret here...
	proxywasm.LogInfof("secret: %v", ctx.pluginContext.Secret())
	return types.ActionContinue
}

Rust

設定資料是從 RootContext 特徵讀取，該特徵會在外掛程式啟動時例項化一次，並在主機外掛程式的 Wasm 執行階段生命週期內保持啟用狀態。RootContext 特徵可用於執行作業，或在多個要求中維持狀態。

外掛程式碼可透過 set_root_context 方法控管用於根層級內容的類別，而根層級內容會例項化串流內容。舉例來說，下列外掛程式程式碼會註冊 MyRootContext，並視需要例項化 MyHttpContext。根層級內容會從外掛程式設定資料讀取密鑰值，並傳遞至串流內容。

use log::info;
use proxy_wasm::traits::*;
use proxy_wasm::types::*;
use std::rc::Rc;

proxy_wasm::main! { {
    proxy_wasm::set_log_level(LogLevel::Trace);
    proxy_wasm::set_root_context(|_| -> Box<dyn RootContext> {
        Box::new(MyRootContext { secret: Rc::new("missing".to_string()) })
    });
} }

struct MyRootContext {
    secret: Rc<String>,
}

impl Context for MyRootContext {}

impl RootContext for MyRootContext {
    fn on_configure(&mut self, _: usize) -> bool {
        if let Some(config_bytes) = self.get_plugin_configuration() {
            self.secret = Rc::new(String::from_utf8(config_bytes).unwrap())
        }
        true
    }

    fn create_http_context(&self, _: u32) -> Option<Box<dyn HttpContext>> {
        Some(Box::new(MyHttpContext {
            secret: self.secret.clone(), // shallow copy, ref count only
        }))
    }

    fn get_type(&self) -> Option<ContextType> {
        Some(ContextType::HttpContext)
    }
}

struct MyHttpContext {
    secret: Rc<String>,
}

impl Context for MyHttpContext {}

impl HttpContext for MyHttpContext {
    fn on_http_request_headers(&mut self, _: usize, _: bool) -> Action {
        // Use secret here...
        info!("secret: {}", self.secret);
        Action::Continue
    }
}

上傳設定檔

如果 on_configure 中要傳送至外掛程式的資料大小超過 900 KiB，請按照「將編譯的外掛程式程式碼上傳至 Artifact Registry」一文所述方法，將資料上傳至 Artifact Registry。在這種情況下，請以 plugin.config 名稱儲存設定檔 (而非 plugin.wasm)。

下一步是建立外掛程式。

建立外掛程式時，您需要提供已上傳 Wasm 模組或圖片的 URI。

建立新版外掛程式碼

如要建立新版外掛程式碼，請編輯外掛程式檔案。然後，如前幾節所述，編譯外掛程式碼、重新封裝，並上傳至 Artifact Registry。

回呼

您編譯成 Wasm 的程式碼可以定義任意方法或函式，但其中有些具有特殊意義。這些方法是在您選擇的語言適用的 Proxy-Wasm SDK 中定義，並對應至 Proxy-Wasm 應用程式二進位檔介面 (ABI) 規格。Service Extensions 會在回應使用者要求或外掛程式生命週期事件時，呼叫這些回呼。

下表列出這些回呼，並依據一般叫用順序排序：

回呼名稱和說明 C++ 方法名稱 Go 方法名稱 Rust 方法名稱
START_PLUGIN：外掛程式啟動時會叫用這個方法。 RootContext::onStart VMContext.OnVmStart RootContext::on_vm_start
CONFIGURE_PLUGIN：外掛程式啟動後會呼叫這個函式，向外掛程式提供設定資料。 RootContext::onConfigure PluginContext.OnPluginStart RootContext::on_configure
CREATE_CONTEXT：建立新的串流內容時會叫用。每個串流都對應至用戶端 HTTP 要求。 Context::onCreate PluginContext.NewHttpContext RootContext::create_http_context
HTTP_REQUEST_HEADERS：用於處理 HTTP 要求標頭。 Context::onRequestHeaders HttpContext.OnHttpRequestHeaders HttpContext::on_http_request_headers
HTTP_REQUEST_BODY：重複叫用，處理 HTTP 要求主體區塊。 Context::onRequestBody HttpContext.OnHttpRequestBody HttpContext::on_http_request_body
HTTP_RESPONSE_HEADERS：用於處理 HTTP 回應標頭。 Context::onResponseHeaders HttpContext.OnHttpResponseHeaders HttpContext::on_http_response_headers
HTTP_RESPONSE_BODY：重複叫用，以處理 HTTP 回應主體區塊。 Context::onResponseBody HttpContext.OnHttpResponseBody HttpContext::on_http_response_body
DONE：外掛程式處理完成時會叫用這個方法。 Context::onDone HttpContext.OnHttpStreamDone Context::on_done
DELETE：在刪除對應於用戶端 HTTP 要求的串流內容物件時叫用。 Context::onDelete (沒有回呼) (沒有回呼)

後續步驟