※本記事は、Viral Modiによる”OCI SDK for .NET is now available for your .NET Projects“を翻訳したものです。
2020年7月23日
このブログは、Oracle Cloudの.NET向けソフトウェア開発キット（SDK）をご紹介いたします。Oracle Cloud SDK for .NETは、Oracle Cloudにて利用できる一連の開発者向けツールの1つとしてリリースされました。ちなみにOracle Cloud Infrastructureでは現在、Java、Python、GO、Ruby、TypeScript、.NET/C#.向けのSDKをサポートしています。今回は、Azureの.NET開発者向けにOracle Cloudで利用可能なプラットフォームを提供するということで、これによりOracle CloudとMicrosoft Azureのパートナーシップがさらに強化されることとなります。
前提条件
私は仕事で複数の開発者SDKとコマンドライン・インターフェース（CLI）を使用しているため、アプリケーション・コードのランタイムの構成情報ではなく、自身の設定用構成ファイルを使用することにします。構成ファイルがあることで、共通構成を使用することも可能になります。私の構成ファイルは、以下のコードでもわかるとおり、デフォルトの保存場所である~/.oci/configに置かれています。
| [DEFAULT] | |
| user=ocid1.user.oc1.. | |
| fingerprint=f7:12:34:56:78:90:ab:bc:cd:de:ef:98:87:65:43:21 | |
| key_file=/Users/viralmodi/.oci/my_oci_api_key.pem | |
| tenancy=ocid1.tenancy.oc1.. | |
| region=us-phoenix-1 |
.NETアプリケーション内でSDKを使用するには
この.NET向けSDKは、.NETコンソール・アプリケーション、デスクトップアプリケーション、または.NETクラスのライブラリにて使用できます。.NETに対応した統合開発環境（IDE）であれば、大半の場合、これらのタイプのプロジェクトを作成することができます。今回は、コンソール・アプリケーションのプロジェクトを作成することにします。
プロジェクトが作成できたら、IDEにて提供されているNuGetパッケージ・マネージャ・ウィンドウにて、Oracle Cloudの.NET SDKパッケージをインストールします。このウィンドウにて”OCI.DotNetSDK”と入力してOracle Cloudの.NETパッケージを検索します。またはNuGetパッケージ・マネージャにて.NET SDKを参照すると、すべてのOracle Cloud .NETパッケージが表示されます。
一般的なIDEにおいてNuGetパッケージをインストールする方法については、以下のリソースを参照してください。
IDEを使用していない場合は、シェル内のプロジェクトのルート・ディレクトリにて次の.NET CLIツールコマンドを使用することで、Oracle Cloud Infrastructureのアイデンティティ・サービス向けの.NETパッケージをインストールできます。
dotnet add package OCI.DotNetSDK.Identity -v 1.0.0
これにより、パッケージに含まれているすべての依存関係が抽出されます。この例では、Oracle Cloud SDK for .NETから提供されている.NETインプリメンテーションを使用して、アイデンティティ・サービスのコンパートメントをリストするためのREST APIを呼び出します。
以下のスクリーンショットでもわかるとおり、インストールにはRider IDEを使用しています。
これでOracle Cloud SDK for .NETを使用するために必要なインストールと構成が完了しました。ここからはアプリケーションのためのコードの記述に移ります。大半のIDEでは、ソース・コードを記述していけば自動入力されるので、非常に便利です。この例では、”using”ディレクティブにて、アプリケーションに以下のタイプを使用しています。
| using System; | |
| using System.Threading.Tasks; | |
| using Oci.Common.Auth; | |
| using Oci.IdentityService; | |
| using Oci.IdentityService.Requests; | |
| using Oci.IdentityService.Responses; |
次に、以下のようにコンパートメントOCIDを初期設定します。
| private static String compartmentId = “ocid1.tenancy.oc1..“; |
なおOCIDの値は、セキュリティ上の理由により一部が非表示になっています。
構成時にサービス・クライアントに渡される認証プロバイダを作成します。認証プロバイダでは、その名のとおり、Oracle Cloud Infrastructureの各サービスによるリクエストを認証します。今回の例では、アイデンティティ・クライアントの裏付けに際して認証プロバイダを渡します。構成ファイルはすでに前提条件の一環として作成済みであるため、Oci.Common.AuthモジュールのConfigFileAuthenticationDetailsProviderを使用します。ここでは構成ファイルのデフォルトのプロファイルを使用していますが、必要に応じて好きなプロファイルを使用することができます。
| var authProvider = new ConfigFileAuthenticationDetailsProvider(“DEFAULT“); |
なお、ランタイム時に構成を渡す場合は、SimpleAuthenticationDetailsProviderを使用します。
次に、authProviderを渡すIdentityClientのインスタンスを作成します。
| var client = new IdentityClient(authProvider); |
リクエストに必要な必須パラメータにてListCompartmentRequest を構成します。今回は、コンパートメントOCIDを渡します。
| var listCompartmentsRequest = new ListCompartmentsRequest | |
| { | |
| CompartmentId = compartmentId | |
| }; |
この例では、.NET SDKのページネーション機能を使用します。これにより、コンパートメントのリストのような大量のアイテムをシンプルな方法で取得することができます。.NET SDKでは以下のページネーション・メカニズムに対応しています。
- リスト呼出しを作り、次のページ・トークンを手動で処理することで、すべてのレコードを取得する。
- 各サービス・クライアントにより公開されているページネーションを使用して、サービス呼出しへのレスポンス（Oracle Cloud SDK Responseオブジェクト）を繰返し処理する。
- 各サービス・クライアントにより公開されているページネーションを使用して、サービス呼出しから返されたモデルとリソースを繰返し処理する。
この例では、ページネーション・メソッドにて、テナンシのルート・コンパートメントからコンパートメント・レコードを取得します。テナンシのOCIDは、それ自体がOracle Cloudのすべてのアカウントのルート・コンパートメントOCIDになります。
アイデンティティ・クライアントのページネータとクラス内のRecordEnumeratorリスト呼出しを使用します。この呼出しでは、IEnumerable<コンパートメント>タイプの列挙子が返されるので、リクエストにて渡されるコンパートメントOCIDのすべてのサブコンパートメントにこれを繰り返し使用することができます。
| try | |
| { | |
| // Using Identity client paginator and its record enumerator to iterate through all compartments | |
| var compartments = client.Paginators.ListCompartmentsRecordEnumerator(listCompartmentsRequest); | |
| foreach (var compartment in compartments) | |
| { | |
| Console.WriteLine(“{0, 30} | {1, 60} | {2, 60}“, | |
| compartment.Name, | |
| compartment.Description, | |
| compartment.Id); | |
| } | |
| } | |
| catch (Exception e) | |
| { | |
| Console.WriteLine(“Failed to call List Compartments “ + e.Message); | |
| } |
ここでコンソール・アプリケーションを保存し、構築して実行すると、以下のインプットが表示されます（セキュリティ上の理由で、コンパート名は変更され、OCIDは一部が非表示になっています）。
| source_dotnetsdk1.sCdm2sWV | source compartment | ocid1.compartment.oc1.. | |
| source_dotnetsdk2.MTCBvYR8 | source compartment | ocid1.compartment.oc1.. | |
| source_dotnetsdk3.JLfWRqsX | source compartment | ocid1.compartment.oc1.. | |
| source_dotnetsdk4.c4Dh9Bht | source compartment | ocid1.compartment.oc1.. | |
| target_dotnetsdk1.HDbFwat0 | target compartment | ocid1.compartment.oc1.. | |
| target_dotnetsdk2.90WbFnEJ | target compartment | ocid1.compartment.oc1.. | |
| target_dotnetsdk3.01JaKkYG | target compartment | ocid1.compartment.oc1.. | |
| target_dotnetsdk4.WaYvdMUj | target compartment | ocid1.compartment.oc1.. | |
| target_dotnetsdk5.tdmO3sbW | target compartment | ocid1.compartment.oc1.. | |
| TeamSandbox | Sandbox for team members to do manual testing, etc. | ocid1.compartment.oc1.. |
IDEを使用している場合は、そのコードで使用されるメソッドの自動完了が可能で、また”var”を使用している場合など、各Oracle Cloud APIの呼出しに対する戻りタイプの情報も提供されます。IDEのデコンパイラでもコードを調べることができ、 オラクルのGitHubにアクセスして、ソース・コードを確認することができます。またOracle Cloud SDK for .NETのAPIリファレンスは、すべての.NET開発者にとって総合的なリファレンスとなっています。
例：リージョンを非同期リストするためのAPIの呼出し
この例では、ListRegionsを呼び出して、Oracle Cloud Infrastructureのすべてのリージョンをリストします。しかしリージョンの数は少なく、固定されているため、このREST APIではページネーションはサポートされていません。そこでこのAPIの使用に際しては、C#の“async and await”コンセプトを用いることにします。大半の.NET SDKの呼出しは非同期であり、System.Threading.Tasks.Taskを使用して追跡することができます。これは、.NET/C#で提供される非同期プログラミングモデルの基礎を形成するものです。
| private static async Task ListOciRegions() | |
| { | |
| // Accepts profile name and creates a auth provider based on config file | |
| var authProvider = new ConfigFileAuthenticationDetailsProvider(“DEFAULT“); | |
| // Create a client for the service to enable using its APIs | |
| var client = new IdentityClient(authProvider); | |
| // List regions | |
| var listRegionsRequest = new ListRegionsRequest(); | |
| try | |
| { | |
| Task <ListRegionsResponse> regRespTask = client.ListRegions(listRegionsRequest); | |
| var listRegionsResponse = await regRespTask; | |
| foreach (Oci.IdentityService.Models.Region reg in listRegionsResponse.Items) | |
| { | |
| Console.WriteLine(reg.Key + “ : “ + reg.Name); | |
| } | |
| } | |
| catch (Exception e) | |
| { | |
| Console.WriteLine(“Failed to call List Regions “+e.Message); | |
| } | |
| } |
このAPIによる結果は以下のとおりです。
| AMS : eu-amsterdam-1 | |
| BOM : ap-mumbai-1 | |
| FRA : eu-frankfurt-1 | |
| GRU : sa-saopaulo-1 | |
| HYD : ap-hyderabad-1 | |
| IAD : us-ashburn-1 | |
| ICN : ap-seoul-1 | |
| JED : me-jeddah-1 | |
| KIX : ap-osaka-1 | |
| LHR : uk-london-1 | |
| MEL : ap-melbourne-1 | |
| NRT : ap-tokyo-1 | |
| PHX : us-phoenix-1 | |
| SYD : ap-sydney-1 | |
| YNY : ap-chuncheon-1 | |
| YUL : ca-montreal-1 | |
| YYZ : ca-toronto-1 | |
| ZRH : eu-zurich-1 |
まとめ
このブログでは、最近リリースされたOracle Cloud SDK for .NETを紹介いたしました。具体的には、リクエストや認証プロバイダの作成方法、Oracle Cloudのアイデンティティ・サービスの使い方、クライアントを使用したサービスAPIの呼出し方を説明いたしました。このブログをご覧の方が.NET開発者で、現在Oracle Cloud Infrastructureを使用されている場合は、ぜひこの.NET SDKを試してみてください。またご質問やご意見がありましたら、コメントをお送りただくか、ドキュメントをご参照ください。
また以下のリソースも.NET SDKの理解に役立ちます。
- Oracle Cloud SDK for .NETの公式ドキュメント
- .NET SDKのリファレンス
- GitHub oci-dotnet-sdkレポジトリ（オープン・ソースで、外部からの協力が可能）
- .NET SDKを使用してOracle Cloudのサービスおよび機能を活用するための例
- NuGetパッケージ・マネージャの各種.NET SDK
- Oracle Cloud Infrastructureの開発者ツールを使用するための前提条件