Google Cloud Platform サービスの Java 慣用クライアント。
個々の Google Cloud サービスと対話する Java アプリケーションを開発するためのライブラリは、GitHub と Maven Central で利用できます。
クライアント | リリースレベル | バージョン |
---|---|---|
AI プラットフォーム ノートブック | ||
APIゲートウェイ | ||
API キー API | ||
アクセス承認 | ||
アドバイザリー通知 API | ||
アロイDB | ||
AlloyDB コネクタ | ||
分析ハブ API | ||
Apigee Connect | ||
App Engine 管理 API | ||
アーティファクトレジストリ | ||
資産目録 | ||
政府向けの確実なワークロード | ||
自動ML | ||
バックアップおよび DR サービス API | ||
BigQuery | ||
BigQuery 接続 | ||
BigQuery データ転送サービス | ||
BigQuery の予約 | ||
BigQuery ストレージ | ||
ビッグテーブル | ||
Bigtable Hbase クライアント | ||
請求する | ||
請求予算 | ||
バイナリ認証 | ||
建てる | ||
CCAIの洞察 | ||
認証局サービス | ||
チャネルサービス | ||
作曲家 | ||
コンピューティング エンジン | ||
コネクトゲートウェイAPI | ||
コンテナ分析 | ||
コントロールパートナー API | ||
DNS | ||
データカタログ | ||
データ融合 | ||
データリネージ | ||
データ損失防止 | ||
データベース移行サービス | ||
データプレックス | ||
データプロシージャ | ||
Dataproc メタストア | ||
データストア | ||
データストリーム | ||
デバッガ | ||
展開する | ||
ダイアログフロー API | ||
ディスカバリーエンジンAPI | ||
分散エッジ | ||
分散型エッジネットワーク API | ||
ドキュメントAI | ||
ドメイン | ||
重要な連絡先 API | ||
イヴェンターク | ||
ファイルストア API | ||
ファイヤーストア | ||
フリートのルーティング | ||
機能 | ||
GKE ハブ API | ||
私は | ||
IAM管理API | ||
IAM ポリシーのトラブルシューティング API | ||
IAM サービスアカウント認証情報 API | ||
アイデンティティ・アクセス・コンテキスト・マネージャー | ||
ID 認識プロキシ API | ||
インフラストラクチャマネージャー API | ||
モノのインターネット (IoT) コア | ||
侵入検知システム | ||
鍵管理サービス | ||
Kubernetes エンジン | ||
ロギング | ||
Microsoft Active Directoryのマネージドサービス | ||
メムキャッシュ | ||
モニタリングダッシュボード | ||
自然言語 | ||
ネットワーク接続センター | ||
ネットワーク管理API | ||
ネットワークセキュリティAPI | ||
OS構成API | ||
OSログイン | ||
組織方針 | ||
プロファイラー | ||
パブ/サブ | ||
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 トレース | ||
ストレージ | ||
ストレージ転送サービス | ||
TPU | ||
人材ソリューション | ||
タスク | ||
通信オートメーション API | ||
テキスト読み上げ | ||
翻訳 | ||
VMの移行 | ||
頂点AI | ||
VertexAI API | ||
ビデオインテリジェンス | ||
ビデオスティッチャー API | ||
ビデオトランスコーダ | ||
ビジョン | ||
ウェブリスク | ||
ワークフローの実行 | ||
ワークフロー | ||
ワークスペース アドオン API | ||
ワークステーション | ||
reCAPTCHA エンタープライズ | ||
APIハブAPI | ||
アド マネージャー API | ||
アドレス検証API | ||
分析管理者 | ||
分析データ | ||
分析ハブ | ||
Anthos マルチクラウド | ||
Apache Kafka API のマネージド サービス | ||
アプリハブAPI | ||
エリア120テーブル | ||
GKE のバックアップ | ||
ベアメタルソリューション | ||
バッチ | ||
BeyondCorp AppConnections | ||
BeyondCorp AppConnectors | ||
BeyondCorp アプリゲートウェイ | ||
BeyondCorp ClientConnectorServices | ||
BeyondCorp クライアントゲートウェイ | ||
ビッグレイク | ||
BigQuery データポリシー API | ||
BigQuery の移行 | ||
CSS API | ||
証明書マネージャー | ||
チャットAPI | ||
商業消費者調達 | ||
機密コンピューティング API | ||
コネクトゲートウェイAPI | ||
データのラベル付け | ||
データフロー | ||
データフォーム | ||
開発者接続API | ||
ダイアログフローCX | ||
ドキュメントAIウェアハウス | ||
エンタープライズナレッジグラフ | ||
エラー報告 | ||
イブンターク出版 | ||
GDC ハードウェア管理 API | ||
KMS インベントリ API | ||
ライフサイエンス | ||
ライブストリームAPI | ||
ロギング ログバック アペンダ | ||
ロギングサーブレットイニシャライザ | ||
マップ プラットフォーム データセット API | ||
マーケティング プラットフォーム管理 API | ||
メディア翻訳 API | ||
APIに会う | ||
Redis API 用の Memorystore | ||
マーチャントAPI | ||
マーチャントAPI | ||
マーチャントAPI | ||
マーチャントAPI | ||
マーチャントAPI | ||
マーチャントAPI | ||
販売者コンバージョン API | ||
マーチャント LFP API | ||
販売者通知 API | ||
マーチャントクォータ API | ||
移行センター API | ||
モニタリングメトリクスの範囲 | ||
ストレージ用の NIO ファイルシステム プロバイダー | ||
ネットアップ API | ||
ネットワークサービスAPI | ||
Oracleデータベース@API | ||
パラレルストア API | ||
フィッシング対策 | ||
プレイス API (新規) | ||
Places Insights API | ||
ポリシーシミュレーターAPI | ||
プライベートカタログ | ||
特権アクセスマネージャー API | ||
Pub/Sub Lite Flink コネクタ | ||
迅速な移行評価 API | ||
レコメンドAI | ||
レジストリAPI | ||
ルート最適化API | ||
走る | ||
Security Command Center 設定 API | ||
サービスヘルス API | ||
ソーラーAPI | ||
ストレージインサイトAPI | ||
サポートAPI | ||
VMware エンジン | ||
ビジョンAI API | ||
ワークスペースイベントAPI |
サービスがリストされていない場合、google-api-java-client は従来の REST インターフェースを使用して追加の Google Cloud API とインターフェースします。
Java アプリケーションを構築する場合は、表にリストされているライブラリを優先する必要があります。
ほとんどのgoogle-cloud
ライブラリにはプロジェクト ID が必要です。このプロジェクト ID を指定するには複数の方法があります。
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 を決定し、値が見つかると停止します。
GOOGLE_CLOUD_PROJECT
で指定されたプロジェクト IDGOOGLE_APPLICATION_CREDENTIALS
環境変数が指す JSON 認証情報ファイルで指定されたプロジェクト 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 を参照してください。
Compute Engine、Kubernetes Engine、App Engine などの Google Cloud Platform 環境から Google Cloud ライブラリを使用する場合、追加の認証手順は必要ありません。
例えば:
Storage storage = StorageOptions . getDefaultInstance (). getService ();
または:
CloudTasksClient cloudTasksClient = CloudTasksClient . create ();
JSON サービス アカウント キーを生成します。
そのキーをダウンロードした後、次のいずれかを実行する必要があります。
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json
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 アクセス トークンをお持ちの場合は、それを使用して認証できます (この場合、アクセス トークンは自動的に更新されないことに注意してください)。
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
環境変数が指す認証情報ファイルgcloud auth application-default login
コマンドによって提供される認証情報API キーによる認証は、いくつかの Google Cloud API でサポートされています。
私たちは API キーのエクスペリエンスを改善する方法を積極的に模索しています。現在、Java クライアント ライブラリで API キーを使用するには、関連するサービス クライアントのヘッダーを手動で設定する必要があります。
たとえば、言語サービスで 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 を使用したよりカスタムなプロキシの場合は、 ProxyDetector
ManagedChannelBuilder
に提供する必要があります。
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 インスタンスまたは Dataflow パイプラインのプロビジョニング) によく使用されます。最初の 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.
}
ポーリング操作には、サービスごとに異なるデフォルトのタイムアウトがあります。ライブラリは、次のメッセージを含むjava.util.concurrent.CancellationException
をスローします: Task was cancelled.
タイムアウトが操作を超えた場合。 CancellationException
、バックエンド GCP オペレーションがキャンセルされたことを意味するものではありません。この例外は、操作から成功ステータスを受信せずに合計タイムアウトを超過した場合に、クライアント ライブラリからスローされます。当社のクライアント ライブラリは、各 RPC の OperationTimedPollAlgorithm に設定された構成値を尊重します。
注: クライアント ライブラリは、オペレーションのポーリング メカニズムを処理します。デフォルトでは、手動でステータスをポーリングする必要はありません。
各 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 クラスを共有します。対応するリンクに注目してください。
RPC タイムアウト値は LRO では使用されず、省略することも、デフォルト値 (タイムアウトの場合はDuration.ZERO
、乗数の場合は1.0
) に設定することもできます。
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) アーティファクトの 1 つを使用することをおすすめします。詳細については、「クラウド クライアント ライブラリの使用」を参照してください。
このリポジトリのクライアントを使用するには、Java 8 以降が必要です。
このリポジトリ内のクライアントは、トランスポート層に HTTP または gRPC を使用します。すべての HTTP ベースのクライアントは、すべての環境で動作する必要があります。
gRPC を使用するクライアントの場合、サポートされるプラットフォームは、Forked Tomcat Native がサポートするプラットフォームによって制限されます。つまり、アーキテクチャの場合は x86_64 のみを意味し、オペレーティング システムの場合は Mac OS X、Windows、および Linux を意味します。さらに、gRPC は、スレッド制限によりプラットフォームの使用を制限します。
したがって、次のものはサポートされません。
(特に) 次の環境が動作するはずです。
このライブラリは、Google クラウド サービスを使用するコードのテストの作成に役立つツールを提供します。
テスト ヘルパーの使用方法の詳細については、「テスト」を参照してください。
このライブラリはセマンティック バージョニングに従っていますが、いくつかの追加条件があります。
@BetaApi
または@Experimental
でマークされたコンポーネントは、「1.x」ライブラリ内の「0.x」機能とみなされます。これは、マイナー リリースとパッチ リリースの間で互換性のない方法で変更される可能性があることを意味します。これらの機能は、 @BetaApi
機能を使用するライブラリ B のコンポーネントにも@BetaApi
のマークが付いている場合を除き、それ自体にコンシューマがあるライブラリ "B" では使用しないでください。 @BetaApi
としてマークされた機能は、最終的にマーカーが削除された「1.x」機能になるパス上にあります。
google-cloud-java の特別な例外: gax-java と google-cloud-java は相互に連携して動作するため、 google-cloud-java は、消費コード@BetaApi
を宣言せずに gax-java の@BetaApi
機能に依存することができます。 。このため、gax-java を google-cloud-java とは独立して使用しないでください。
@InternalApi
でマークされたコンポーネントは技術的には公開されていますが、それは Java のアクセス修飾子の制限のためです。 semver の目的では、それらはプライベートであると見なされるべきです。
@InternalExtensionOnly
でマークされたインターフェイスはパブリックですが、内部クラスによってのみ実装される必要があります。 semver の目的で、当社はデフォルトの実装 (Java 7 の場合) を使用せずにこれらのインターフェースに追加する権利を留保します。
これらのクライアントは現在開発中であることに注意してください。バージョン 0.xy のリリースには、いつでも下位互換性のない変更が加えられる可能性があります。
安定した品質レベルで定義されたライブラリは安定していることが期待され、ライブラリ内のすべての更新には下位互換性が保証されます。下位互換性のない変更があると、メジャー バージョンが増加します (1.xy -> 2.0.0)。
プレビュー品質レベルで定義されたライブラリはまだ作業中であるため、下位互換性のない更新が行われる可能性が高くなります。さらに、プレビュー ライブラリがプレビューまたは安定版に昇格する前に非推奨になり、削除される可能性があります。
IntelliJ または Eclipse を使用している場合は、次の IDE プラグインを使用してクライアント ライブラリをプロジェクトに追加できます。
クライアント ライブラリの追加に加えて、プラグインはサービス アカウント キー管理などの追加機能を提供します。詳細については、各プラグインのドキュメントを参照してください。
これらのクライアント ライブラリは、Java 8 ランタイムの App Engine スタンダードおよび App Engine フレキシブル(Compat ランタイムを含む)で使用できます。ライブラリのほとんどは、Java 7 ランタイムの App Engine 標準では動作しません。ただし、データストア、ストレージ、BigQuery は動作するはずです。
このライブラリへの貢献はいつでも歓迎されており、強く奨励されています。
開始方法の詳細については、 google-cloud
の CONTRIBUTING ドキュメントと共有ドキュメントを参照してください。
このプロジェクトは貢献者の行動規範とともにリリースされていることに注意してください。このプロジェクトに参加すると、その規約に従うことに同意したことになります。詳細については、「行動規範」を参照してください。
Apache 2.0 - 詳細については、「ライセンス」を参照してください。