舊版套裝組合服務的遠端 API

Java SDK 包含稱為 Remote API 的程式庫，可讓您用清楚明瞭的方式從任何 Java 應用程式存取 App Engine 服務。例如，您可以使用 Remote API，從本機電腦上執行的應用程式存取實際工作環境的資料儲存庫。您也可以使用 Remote API，從某個 App Engine 應用程式存取另一個 App Engine 應用程式的資料儲存庫。

重要事項： 不支援透過網路 Proxy 使用 RemoteApi。

注意： 不建議使用此解決方案：使用此 API 的應用程式只能在 Java 8 執行階段中執行，且必須升級至建議的解決方案，才能遷移至 Java 11/17 執行階段。

在伺服器上設定 Remote API

Remote API 的伺服器元件是 Java Servlet，其為 Java 適用的 App Engine 執行階段的一部分。這個 Servlet 會接收來自 Remote API 用戶端的要求、將要求分派給適當的後端服務，然後將服務呼叫的結果傳回給用戶端。如要安裝 Remote API Servlet，請在 web.xml 中新增下列項目：

<servlet>
  <display-name>Remote API Servlet</display-name>
  <servlet-name>RemoteApiServlet</servlet-name>
  <servlet-class>com.google.apphosting.utils.remoteapi.RemoteApiServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>RemoteApiServlet</servlet-name>
  <url-pattern>/remote_api</url-pattern>
</servlet-mapping>

注意：如要進一步瞭解如何使用 web.xml，請參閱部署作業描述元頁面。

如果沒有已通過驗證的使用者，或者已通過驗證的使用者不是應用程式的管理員，則該 Servlet 會傳回錯誤，因此無需設定任何額外的安全措施。使用這些設定部署應用程式後，安裝 Remote API 用戶端的任何應用程式都能使用其服務。包括使用 Python Remote API 的 Python 用戶端。

在獨立用戶端上設定 Remote API

如要在 Java 應用程式中使用 Remote API 的用戶端元件，請將 ${SDK_ROOT}/lib/impl/appengine-api.jar 和 ${SDK_ROOT}/lib/appengine-remote-api.jar 新增至類別路徑。然後，在您的程式碼中設定並安裝 Remote API：

import com.google.appengine.tools.remoteapi.RemoteApiInstaller;
import com.google.appengine.tools.remoteapi.RemoteApiOptions;

// ...
RemoteApiOptions options = new RemoteApiOptions()
    .server("[APP_ID].[REGION_ID].r.appspot.com", 443)
    .useApplicationDefaultCredential();

RemoteApiInstaller installer = new RemoteApiInstaller();
installer.install(options);
// ... all API calls executed remotely
installer.uninstall();

Remote API 用戶端將會依賴使用 OAuth 2.0 的應用程式預設憑證。

為了取得憑證，請執行：

gcloud auth application-default login

注意： 對 useApplicationDefaultCredential() 發出的 Remote API 呼叫只能使用 gcloud 指令提供的憑證。

您可以輕鬆地連線至在開發伺服器本機執行的 App Engine 應用程式：

RemoteApiOptions options = new RemoteApiOptions()
    .server("localhost", 8888) // server name must equal "localhost"
    .useDevelopmentServerCredential();

以下是一個完整的 Java 應用程式，此程式在執行時會將實體插入資料儲存庫：

public class RemoteApiExample {

  public static void main(String[] args) throws IOException {
    String serverString = args[0];
    RemoteApiOptions options;
    if (serverString.equals("localhost")) {
      options = new RemoteApiOptions().server(serverString,
        8080).useDevelopmentServerCredential();
    } else {
      options = new RemoteApiOptions().server(serverString,
        443).useApplicationDefaultCredential();
    }
    RemoteApiInstaller installer = new RemoteApiInstaller();
    installer.install(options);
    try {
      DatastoreService ds = DatastoreServiceFactory.getDatastoreService();
      System.out.println("Key of new entity is " + ds.put(new Entity("Hello Remote API!")));
    } finally {
      installer.uninstall();
    }
  }
}

在 App Engine 用戶端上設定 Remote API

您也可以使用 Remote API，從某個 App Engine 應用程式存取另一個 App Engine 應用程式的服務。您需要將 ${SDK_ROOT}/lib/appengine-remote-api.jar 新增至 WEB-INF/lib 目錄，然後在用戶端 App Engine 應用程式中，設定並安裝 Remote API，就像在獨立 Java 用戶端中一樣。

請注意，RemoteApiInstaller 只會在執行安裝作業的執行緒上安裝 Remote API，因此請小心不要在執行緒之間共用這個類別的執行個體。

將 Remote API 與 Maven 搭配使用

如要在 Maven 專案中使用 Remote API 功能，請將以下依附元件新增至專案 pom.xml 檔案：

<dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-remote-api</artifactId>
  <version>1.9.64</version>
</dependency>
<dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-api-1.0-sdk</artifactId>
  <version>1.9.64</version>
</dependency>

限制與最佳做法

remote_api 模組會盡所有可能，使其運作方式與原生 App Engine 資料儲存庫完全相同。在某些情況下，這意謂著該運作效率可能會較原有運作方式低。使用 remote_api 時，必須記住幾個重點：

每個資料儲存庫要求都需要一去一回

由於您是透過 HTTP 存取資料儲存庫，因此產生的負擔與延遲會比本機存取略高一些。為加快速度並減少負荷，請透過批次取得與放入，以及批次從查詢擷取實體，嘗試限制去回的次數。無論對於 remote_api，還是在一般情況下使用資料儲存庫，這都是非常好的建議，因為系統只會將批次作業視為單一資料儲存庫作業。

向 remote_api 發出的要求會使用配額

由於 remote_api 透過 HTTP 操作，因此您每次呼叫資料儲存庫都會針對 HTTP 要求產生配額使用量、接收和傳送的位元組，以及您預期的一般資料儲存庫配額。如果您是透過 remote_api 執行批次更新，請務必記住這一點。

適用 1 MB API 限制

跟在本機執行時一樣，API 要求和回應的 1MB 限制仍然適用。如果您的實體數量特別龐大，您可能需要限制一次擷取或放入的數量，以符合這個限制。不幸的是，這會與去回次數的最小化發生衝突，因此最好的做法是，使用不超過要求或回應限制的最大批次操作數量。但是，就大多數的實體來說，這不會是一個問題。

避免疊代處理查詢

疊代處理查詢時，SDK 會從資料儲存庫中擷取 20 個批次的實體，並在用完現有批次時擷取新的批次。因為 remote_api 必須透過個別要求擷取每批實體，所以效率很低。因此，remote_api 改為使用偏移功能深入結果，為每個批次執行全新的查詢。

如果您知道您需要的實體數量，您可以要求所需數量，即可透過單一要求完成整個擷取。

如果您不知道需要多少實體，則可以使用游標有效地疊代處理大型結果集。這也可以讓您規避一般資料儲存庫查詢的 1000 個實體限制。

交易的效率較低

為了透過 remote_api 實作交易，將累積在交易內部擷取的實體資訊，以及在交易內部放置或刪除的實體副本。認可交易之後，系統會將這些資訊全數傳送至 App Engine 伺服器，而其必須在此處再次擷取交易所使用的所有實體、確認這些實體未遭到修改，然後放入並刪除交易所做的所有變更，再予以認可。如果發生衝突，伺服器會退回交易，並通知用戶端，然後用戶端必須重複整個過程。

這個方法是行得通的，而且會在本機資料儲存庫上完整重現交易所提供的功能，不過效率較低。總而言之，您可以在需要時使用交易，但是為求效率，請嘗試限制您執行的交易數量與複雜性。