google cloud java下載 - google cloud java原始碼下載

Google Cloud Java 用戶端程式庫

Google Cloud Platform 服務的 Java 慣用客戶端。

谷歌雲上的 Java

支援的API

GitHub 和 Maven Central 上提供了用於開發與各個 Google Cloud 服務互動的 Java 應用程式的程式庫：

客戶	發布等級	版本
AI平台筆記本
API網關
API 金鑰 API
准入審批
諮詢通知 API
合金資料庫
AlloyDB 連接器
分析中心 API
Apigee 連接
App Engine 管理 API
工件登記處
資產盤點
政府工作量有保障
自動機器學習
備份災難服務API
大查詢
BigQuery 連接
BigQuery 資料傳輸服務
BigQuery 預訂
BigQuery 存儲
大表
Bigtable Hbase 用戶端
計費
計費預算
二進制授權
建造
CCAI 見解
證書頒發機構服務
通路服務
作曲家
計算引擎
連接網關API
容器分析
控制合作夥伴API
域名系統
數據目錄
數據融合
數據沿襲
資料遺失防護
資料庫遷移服務
資料中心
資料處理程序
Dataproc 元存儲
資料儲存
資料流
偵錯工具
部署
對話串流API
發現引擎API
分散式邊緣
分散式邊緣網路API
文件人工智慧
網域
基本聯絡人 API
事件弧
檔案儲存API
火庫
車隊路線
功能
GKE 中心 API
我是
IAM 管理 API
IAM 策略疑難排解 API
IAM 服務帳戶憑證 API
身分存取上下文管理器
身分識別代理 API
基礎設施管理器API
物聯網 (IoT) 核心
入侵偵測系統
密鑰管理服務
Kubernetes 引擎
記錄
Microsoft Active Directory 託管服務
記憶體快取
監控儀表板
自然語言
網路連線中心
網路管理API
網路安全API
作業系統配置API
作業系統登入
組織政策
分析器
發布/訂閱
Pub/Sub 組 Kafka 連接器
發布/訂閱精簡版
Pub/Sub Lite Kafka Shim
Pub/Sub Lite Spark 連接器
公共憑證授權單位 API
配額API
推薦人
雷迪斯
資源管理器API
資源設定API
零售
路線API
調度程式
秘密管理
安全性來源管理器 API
安全中心管理API
安全指揮中心
安全態勢API
安全掃描儀
無伺服器 VPC 訪問
服務控制API
服務目錄
服務管理API
服務使用情況
殼
扳手
扳手 JDBC
演講
Stackdriver 監控
Stackdriver 追蹤
貯存
儲存傳輸服務
熱塑性聚氨酯
人才解決方案
任務
電信自動化 API
文字轉語音
翻譯
虛擬機器遷移
頂點人工智慧
頂點人工智慧API
視訊智能
視訊拼接器 API
視訊轉碼器
想像
網路風險
工作流程執行
工作流程
工作區附加 API
工作站
reCAPTCHA 企業版
API 中心 API
廣告管理器 API
地址驗證 API
分析管理員
分析數據
分析中心
Anthos 多雲
Apache Kafka API 託管服務
應用程式中心API
120桌區
GKE 備份
裸機解決方案
批次
BeyondCorp 應用程式連接
BeyondCorp 應用程式連接器
BeyondCorp 應用程式網關
BeyondCorp 用戶端連接器服務
BeyondCorp 用戶端網關
大湖
BigQuery 資料策略 API
BigQuery 遷移
CSS API
證書管理器
聊天API
商業消費者採購
機密計算API
連接網關API
數據標籤
資料流
數據表
開發者連接 API
Dialogflow CX
文檔AI倉庫
企業知識圖譜
錯誤報告
事件弧出版
GDC 硬體管理 API
KMS庫存API
生命科學
直播API
錄音 Logback Appender
記錄 Servlet 初始化程序
地圖平台資料集 API
行銷平台管理API
媒體翻譯API
滿足API
用於 Redis API 的記憶體存儲
商家API
商家API
商家API
商家API
商家API
商家API
商家轉換API
商家LFP API
商家通知API
商家配額API
遷移中心API
監控指標範圍
用於儲存的 NIO 檔案系統提供程序
網路應用程式介面
網路服務API
Oracle資料庫@API
並行儲存API
網路釣魚防護
地點 API（新）
地點見解 API
政策模擬器API
私人目錄
特權存取管理器 API
Pub/Sub Lite Flink 連接器
快速遷移評估 API
推薦人工智慧
註冊表API
路線優化API
跑步
安全指揮中心設定 API
服務健康API
太陽能API
儲存洞察 API
支援API
VMware引擎
視覺人工智慧API
工作區事件 API

如果未列出該服務，google-api-java-client 將使用舊版 REST 介面與其他 Google Cloud API 進行互動。

建立 Java 應用程式時，應優先考慮表中列出的庫。

指定項目 ID

大多數google-cloud函式庫都需要專案 ID。有多種方法可以指定此項目 ID。

在 Compute/App Engine 中使用google-cloud函式庫時，無需指定專案 ID。它是從生產環境自動推斷的。
在其他地方使用google-cloud時，您可以執行以下操作之一：

建置服務選項時提供項目 ID。例如，要使用 ID 為“PROJECT_ID”的專案中的資料存儲，您可以編寫：
```
 Datastore datastore = DatastoreOptions . newBuilder (). setProjectId ( "PROJECT_ID" ). build (). getService ();
```
將環境變數GOOGLE_CLOUD_PROJECT指定為您所需的項目 ID。
使用 Google Cloud SDK 設定項目 ID。若要使用 SDK，請下載 SDK（如果尚未下載），然後從命令列設定專案 ID。例如：
```
 gcloud config set project PROJECT_ID
```

google-cloud會依照列出的順序從以下來源決定項目 ID，一旦找到值就停止：

建置服務選項時提供的項目 ID
由環境變數GOOGLE_CLOUD_PROJECT指定的項目 ID
App Engine/Compute Engine 專案 ID
GOOGLE_APPLICATION_CREDENTIALS環境變數所指向的 JSON 憑證檔案中指定的項目 ID
Google Cloud SDK 專案 ID

如果庫可能明確需要項目 ID，我們提供一個可以提供推斷的項目 ID 的幫助程序：

  import com . google . cloud . ServiceOptions ;
  ...
  String projectId = ServiceOptions . getDefaultProjectId ();

驗證

google-cloud-java使用 https://github.com/googleapis/google-auth-library-java 來驗證請求。 google-auth-library-java支援多種身份驗證類型；有關更多詳細信息，請參閱專案的 README 和 javadoc。

谷歌雲端平台環境

從 Google Cloud Platform 環境（例如 Compute Engine、Kubernetes Engine 或 App Engine）使用 Google Cloud 程式庫時，無需執行額外的驗證步驟。

例如：

 Storage storage = StorageOptions . getDefaultInstance (). getService ();

或者：

 CloudTasksClient cloudTasksClient = CloudTasksClient . create ();

其他環境

使用服務帳戶（推薦）

產生 JSON 服務帳戶金鑰。

下載該金鑰後，您必須執行下列操作之一：

將環境變數 GOOGLE_APPLICATION_CREDENTIALS 定義為金鑰的位置。例如：

 export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json

建置服務選項時提供 JSON 憑證檔。例如，此儲存物件具有與您的 Google Cloud Storage 資料互動所需的權限：

 Storage storage = StorageOptions . newBuilder ()
    . setCredentials ( ServiceAccountCredentials . fromStream ( new FileInputStream ( "/path/to/my/key.json" )))
    . build ()
    . getService ();

本地開發/測試

如果在本地運行以進行開發/測試，您可以使用 Google Cloud SDK。使用gcloud auth application-default login建立應用程式預設憑證，然後google-cloud將自動偵測此類憑證。

現有 OAuth2 存取權令牌

如果您已經擁有 OAuth2 存取權令牌，則可以使用它進行身份驗證（請注意，在這種情況下，存取權杖不會自動刷新）：

 Credentials credentials = GoogleCredentials . create ( new AccessToken ( accessToken , expirationTime ));
Storage storage = StorageOptions . newBuilder ()
    . setCredentials ( credentials )
    . build ()
    . getService ();

或者：

 Credentials credentials = GoogleCredentials . create ( new AccessToken ( accessToken , expirationTime ));
CloudTasksSettings cloudTasksSettings = CloudTasksSettings . newBuilder ()
    . setCredentialProvider ( FixedCredentialsProvider . create ( credentials ))
    . build ();
CloudTasksClient cloudTasksClient = CloudTasksClient . create ( cloudTasksSettings );

應用程式預設憑證

如果未提供憑證， google-cloud將嘗試使用GoogleCredentials.getApplicationDefault()從環境中偵測它們，這將在以下位置（按順序）搜尋應用程式預設憑證：

GOOGLE_APPLICATION_CREDENTIALS環境變數所指向的憑證文件
Google Cloud SDK gcloud auth application-default login指令提供的憑證
Google App Engine 內建憑證
Google Cloud Shell 內建憑證
Google Compute Engine 內建憑證

使用 API 金鑰進行身份驗證

少數 Google Cloud API 支援使用 API 金鑰進行驗證。

我們正在積極探索改善 API Key 體驗的方法。目前，要將 API Key 與 Java 用戶端程式庫一起使用，您需要手動設定相關服務用戶端的標頭。

例如，若要使用語言服務設定 API 金鑰：

 public LanguageServiceClient createGrpcClientWithApiKey ( String apiKey ) throws Exception {
    // Manually set the api key via the header
    Map < String , String > header = new HashMap < String , String >() { { put ( "x-goog-api-key" , apiKey );}};
    FixedHeaderProvider headerProvider = FixedHeaderProvider . create ( header );

    // Create the client
    TransportChannelProvider transportChannelProvider = InstantiatingGrpcChannelProvider . newBuilder (). setHeaderProvider ( headerProvider ). build ();
    LanguageServiceSettings settings = LanguageServiceSettings . newBuilder (). setTransportChannelProvider ( transportChannelProvider ). build ();
    LanguageServiceClient client = LanguageServiceClient . create ( settings );
    return client ;
  }

使用 REST 的語言客戶端實例化範例：

 public LanguageServiceClient createRestClientWithApiKey ( String apiKey ) throws Exception {
    // Manually set the api key header
    Map < String , String > header = new HashMap < String , String >() { { put ( "x-goog-api-key" , apiKey );}};
    FixedHeaderProvider headerProvider = FixedHeaderProvider . create ( header );

    // Create the client
    TransportChannelProvider transportChannelProvider = InstantiatingHttpJsonChannelProvider . newBuilder (). setHeaderProvider ( headerProvider ). build ();
    LanguageServiceSettings settings = LanguageServiceSettings . newBuilder (). setTransportChannelProvider ( transportChannelProvider ). build ();
    LanguageServiceClient client = LanguageServiceClient . create ( settings );
    return client ;
  }

故障排除

若要取得協助，請按照故障排除文件中的說明進行操作。

配置代理

Google Cloud 用戶端程式庫在與服務的底層通訊中使用 HTTPS 和 gRPC。在這兩種協定中，您可以使用https.proxyHost和（可選） https.proxyPort屬性來設定代理。

gRPC 自訂代理程式配置

對於使用 gRPC 的更自訂代理，您需要向ManagedChannelBuilder提供ProxyDetector ：

 import com . google . api . core . ApiFunction ;
import com . google . api . gax . rpc . TransportChannelProvider ;
import com . google . cloud . tasks . v2 . CloudTasksClient ;
import com . google . cloud . tasks . v2 . CloudTasksSettings ;
import com . google . cloud . tasks . v2 . stub . CloudTasksStubSettings ;
import io . grpc . HttpConnectProxiedSocketAddress ;
import io . grpc . ManagedChannelBuilder ;
import io . grpc . ProxiedSocketAddress ;
import io . grpc . ProxyDetector ;

import javax . annotation . Nullable ;
import java . io . IOException ;
import java . net . InetSocketAddress ;
import java . net . SocketAddress ;

public CloudTasksClient getService () throws IOException {
  TransportChannelProvider transportChannelProvider =
      CloudTasksStubSettings . defaultGrpcTransportProviderBuilder ()
          . setChannelConfigurator (
              new ApiFunction < ManagedChannelBuilder , ManagedChannelBuilder >() {
                @ Override
                public ManagedChannelBuilder apply ( ManagedChannelBuilder managedChannelBuilder ) {
                  return managedChannelBuilder . proxyDetector (
                      new ProxyDetector () {
                        @ Nullable
                        @ Override
                        public ProxiedSocketAddress proxyFor ( SocketAddress socketAddress )
                            throws IOException {
                          return HttpConnectProxiedSocketAddress . newBuilder ()
                              . setUsername ( PROXY_USERNAME )
                              . setPassword ( PROXY_PASSWORD )
                              . setProxyAddress ( new InetSocketAddress ( PROXY_HOST , PROXY_PORT ))
                              . setTargetAddress (( InetSocketAddress ) socketAddress )
                              . build ();
                        }
                      });
                }
              })
          . build ();
  CloudTasksSettings cloudTasksSettings =
      CloudTasksSettings . newBuilder ()
          . setTransportChannelProvider ( transportChannelProvider )
          . build ();
  return CloudTasksClient . create ( cloudTasksSettings );
}

長時間運行的操作

長時間運行操作 (LRO) 通常用於預計需要很長時間才能完成的 API 呼叫（即配置 GCE 實例或資料流管道）。初始 API 呼叫在伺服器上建立一個「操作」並傳回一個操作 ID 以追蹤其進度。 LRO RPC 在呼叫名稱後附加了後綴Async （即clusterControllerClient.createClusterAsync() ）

我們產生的客戶端提供了一個很好的介面來啟動操作然後等待操作完成。這是透過傳回一個OperationFuture來完成的。當在OperationFuture上呼叫get()時，客戶端程式庫將輪詢操作以檢查操作的狀態。

例如，以 google-cloud-dataproc v4.20.0 中的createCluster操作為例：

 try ( ClusterControllerClient clusterControllerClient = ClusterControllerClient . create ()) {
  CreateClusterRequest request =
      CreateClusterRequest . newBuilder ()
          . setProjectId ( "{PROJECT_ID}" )
          . setRegion ( "{REGION}" )
          . setCluster ( Cluster . newBuilder (). build ())
          . setRequestId ( "{REQUEST_ID}" )
          . setActionOnFailedPrimaryWorkers ( FailureAction . forNumber ( 0 ))
          . build ();
  OperationFuture < Cluster , ClusterOperationMetadata > future =
      clusterControllerClient . createClusterOperationCallable (). futureCall ( request );
  // Do something.
  Cluster response = future . get ();
} catch ( CancellationException e ) {
  // Exceeded the default RPC timeout without the Operation completing.
  // Library is no longer polling for the Operation status. Consider 
  // increasing the timeout.
}

LRO 逾時

輪詢操作具有預設逾時，該逾時會因服務而異。該函式庫將拋出java.util.concurrent.CancellationException並顯示訊息： Task was cancelled.如果逾時超過操作。 CancellationException並不表示後端 GCP 操作已取消。當超過總超時而未從操作接收到成功狀態時，用戶端程式庫會拋出此異常。我們的客戶端庫尊重每個 RPC 在 OperationTimedPollAlgorithm 中設定的配置值。

注意：客戶端庫為您處理操作的輪詢機制。預設情況下，不需要自己手動輪詢狀態。

預設 LRO 值

每個 LRO RPC 都有一組預先配置的預設值。您可以透過在每個 Client 的StubSettings類別中搜尋來找到這些值。預設的 LRO 設定是在嵌套 Builder 類別的initDefaults()方法內初始化的。

例如，在 google-cloud-aiplatform v3.24.0 中，預設的 OperationTimedPollAlgorithm 具有以下預設值：

 OperationTimedPollAlgorithm . create (
    RetrySettings . newBuilder ()
        . setInitialRetryDelay ( Duration . ofMillis ( 5000L ))
        . setRetryDelayMultiplier ( 1.5 )
        . setMaxRetryDelay ( Duration . ofMillis ( 45000L ))
        . setInitialRpcTimeout ( Duration . ZERO )
        . setRpcTimeoutMultiplier ( 1.0 )
        . setMaxRpcTimeout ( Duration . ZERO )
        . setTotalTimeout ( Duration . ofMillis ( 300000L ))
        . build ())

重試和 LRO 共享相同的 RetrySettings 類別。請注意相應的連結：

總逾時（允許輪詢的最長時間）：5 分鐘
初始重試延遲（第一次輪詢之前的初始延遲）：5 秒
最大重試延遲（每次輪詢之間的最大延遲）：45 秒
重試延遲乘數（增加輪詢延遲的乘數）：1.5

RPC 逾時值在 LRO 中沒有用處，可以省略或設定為預設值（逾時為Duration.ZERO ，或乘數為1.0 ）。

配置 LRO 逾時

若要配置 LRO 值，請建立一個 OperationTimedPollAlgorithm 物件並更新 RPC 的輪詢演算法。例如：

 ClusterControllerSettings . Builder settingsBuilder = ClusterControllerSettings . newBuilder ();
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm . create (
		RetrySettings . newBuilder ()
				. setInitialRetryDelay ( Duration . ofMillis ( 500L ))
				. setRetryDelayMultiplier ( 1.5 )
				. setMaxRetryDelay ( Duration . ofMillis ( 5000L ))
				. setInitialRpcTimeout ( Duration . ZERO ) // ignored
				. setRpcTimeoutMultiplier ( 1.0 ) // ignored
				. setMaxRpcTimeout ( Duration . ZERO ) // ignored
				. setTotalTimeout ( Duration . ofHours ( 24L ))	// set polling timeout to 24 hours
				. build ());
settingsBuilder . createClusterOperationSettings ()
		. setPollingAlgorithm ( timedRetryAlgorithm );
ClusterControllerClient clusterControllerClient = ClusterControllerClient . create ( settingsBuilder . build ());

注意：上面的配置僅修改createClusterOperation RPC 的 LRO 值。客戶端中的其他 RPC 仍將使用每個 RPC 的預先配置 LRO 值。

管理依賴關係

如果您使用多個 Google Cloud 用戶端庫，我們建議您使用我們的物料清單 (BOM) 工件之一來協助管理相依性版本。有關更多信息，請參閱使用雲端客戶端庫。

Java 版本

使用此儲存庫中的用戶端需要 Java 8 或更高版本。

支援的平台

此儲存庫中的用戶端使用 HTTP 或 gRPC 作為傳輸層。所有基於 HTTP 的客戶端都應該在所有環境中運作。

對於使用 gRPC 的客戶端，支援的平台受到 Forked Tomcat Native 支援的平台的限制，對於架構來說僅意味著 x86_64，對於作業系統來說意味著 Mac OS X、Windows 和 Linux。此外，gRPC 還限制了具有線程限制的平台的使用。

因此，不支援以下內容：

安卓
- 考慮一下 Firebase，它包含許多這樣的 API。
- 儘管不受支持，但在許多情況下可以使用這些庫。您可以在此範例儲存庫中找到範例，例如本例，但在應用程式中使用這些庫之前請仔細考慮風險。
Raspberry Pi（因為它在 ARM 架構上運行）
谷歌應用程式引擎標準 Java 7

以下環境應該可以工作（除其他外）：

x86_64 上的獨立 Windows
x86_64 上的獨立 Mac OS X
x86_64 上的獨立 Linux
Google計算引擎（GCE）
Google容器引擎（GKE）
Google App Engine 標準 Java 8 (GAE Std J8)
Google 應用程式引擎 Flex (GAE Flex)
Alpine Linux（Java 11+）

測試

該庫提供了一些工具來幫助為使用谷歌雲端服務的程式碼編寫測試。

請參閱測試以了解有關使用我們的測試助手的更多資訊。

版本控制

該庫遵循語義版本控制，並具有一些附加資格：

標示@BetaApi或@Experimental的元件被視為「1.x」庫中的「0.x」功能。這意味著它們可以以不相容的方式在次要版本和補丁版本之間進行更改。這些功能不應被任何本身俱有使用者的庫「B」使用，除非使用@BetaApi功能的庫 B 的元件也標記有@BetaApi 。標記為@BetaApi功能最終將成為「1.x」功能，並刪除標記。
google-cloud-java 的特殊例外：允許 google-cloud-java 依賴 gax-java 中的@BetaApi功能，而無需聲明使用程式碼@BetaApi ，因為 gax-java 和 google-cloud-java 彼此同步移動。因此，gax-java 不應獨立於 google-cloud-java 使用。
用@InternalApi標記的元件在技術上是公共的，但這只是因為 Java 存取修飾符的限制。就 semver 而言，它們應被視為私有的。
用@InternalExtensionOnly標記的介面是公共的，但只能由內部類別實作。出於 semver 的目的，我們保留在沒有預設實作的情況下新增到這些介面的權利（對於 Java 7）。