基本チュートリアル

Objective-CにおけるgRPCの基本チュートリアルです。

基本チュートリアル

Objective-CにおけるgRPCの基本チュートリアルです。

このチュートリアルでは、Objective-Cプログラマー向けにgRPCの基本的な使い方を紹介します。

この例に従うことで、以下の方法を学ぶことができます。

.protoファイルでサービスを定義する。
Protocol Bufferコンパイラを使用してクライアントコードを生成する。
Objective-C gRPC APIを使用して、サービス用のシンプルなクライアントを作成する。

Protocol Buffersに関する基礎知識があることを前提としています。このチュートリアルの例では、proto3バージョンのProtocol Buffers言語を使用しています。詳細は、proto3言語ガイドとObjective-C生成コードガイドをご覧ください。

なぜgRPCを使うのか？

この例では、クライアントがルート上の地物に関する情報を取得し、ルートの概要を作成し、サーバーや他のクライアントと交通情報などのルート情報を交換できる、シンプルなルートマッピングアプリケーションを使用します。

gRPCを使用すると、.protoファイルでサービスを一度定義し、gRPCがサポートする任意の言語でクライアントとサーバーを生成できます。生成されたクライアントとサーバーは、大規模データセンター内のサーバーから自分のタブレットまで、さまざまな環境で実行できます。異なる言語や環境間の通信の複雑さはすべてgRPCによって処理されます。また、効率的なシリアライゼーション、シンプルなIDL、簡単なインターフェースの更新など、Protocol Buffersを使用するすべての利点を得ることができます。

サンプルコードとセットアップ

このチュートリアルのサンプルコードは、grpc/grpc/examples/objective-c/route_guideにあります。サンプルをダウンロードするには、次のコマンドを実行してgrpcリポジトリをクローンします。

$ git clone -b v1.62.0 --depth 1 --shallow-submodules https://github.com/grpc/grpc
$ cd grpc
$ git submodule update --init

次に、カレントディレクトリをexamples/objective-c/route_guideに変更します。

$ cd examples/objective-c/route_guide

また、Cocoapodsと、クライアントライブラリコード（およびテスト用の別の言語のサーバー）を生成するための関連ツールがインストールされている必要があります。後者は、これらのセットアップ手順に従うことで入手できます。

試してみよう！

サンプルアプリを試すには、ローカルでgRPCサーバーを実行する必要があります。たとえば、このリポジトリのC++サーバーをコンパイルして実行してみましょう。

$ pushd ../../cpp/route_guide
$ make
$ ./route_guide_server &
$ popd

次に、Cocoapodsに.protoファイルのクライアントライブラリを生成してインストールさせます。

$ pod install

（CocoapodsがコンピューターのキャッシュにOpenSSLを持っていない場合、コンパイルに約15分かかります）。

最後に、Cocoapodsによって作成されたXCodeワークスペースを開き、アプリを実行します。呼び出しコードはViewControllers.mで確認でき、結果はXCodeのログコンソールに表示されます。

次のセクションでは、このprotoサービスの定義方法、クライアントライブラリの生成方法、およびそのライブラリを使用するアプリの作成方法について、手順を追って説明します。

サービスの定義

まず、使用しているサービスの定義方法を見てみましょう。gRPC *サービス*とそのメソッドの*リクエスト*と*レスポンス*のタイプは、Protocol Buffersを使用して定義されます。この例の完全な.protoファイルは、examples/protos/route_guide.protoにあります。

サービスを定義するには、.protoファイルで名前付きのserviceを指定します。

service RouteGuide {
   ...
}

次に、サービス定義内でrpcメソッドを定義し、それらのリクエストとレスポンスタイプを指定します。Protocol Buffersでは、4種類のサービスメソッドを定義できます。これらはすべてRouteGuideサービスで使用されます。

クライアントがサーバーにリクエストを送信し、後でレスポンスを受信する*単純RPC*。通常の遠隔手続き呼び出しと同じです。
```
// Obtains the feature at a given position.
rpc GetFeature(Point) returns (Feature) {}
```
クライアントがサーバーにリクエストを送信し、レスポンスメッセージのストリームを受信する*レスポンスストリーミングRPC*。レスポンスストリーミングメソッドを指定するには、*レスポンス*タイプの前にstreamキーワードを配置します。
```
// Obtains the Features available within the given Rectangle.  Results are
// streamed rather than returned at once (e.g. in a response message with a
// repeated field), as the rectangle may cover a large area and contain a
// huge number of features.
rpc ListFeatures(Rectangle) returns (stream Feature) {}
```
クライアントがサーバーにメッセージのシーケンスを送信する*リクエストストリーミングRPC*。クライアントはメッセージの書き込みが完了すると、サーバーがすべてを読み取ってレスポンスを返すまで待機します。リクエストストリーミングメソッドを指定するには、*リクエスト*タイプの前にstreamキーワードを配置します。
```
// Accepts a stream of Points on a route being traversed, returning a
// RouteSummary when traversal is completed.
rpc RecordRoute(stream Point) returns (RouteSummary) {}
```
両側が相手にメッセージのシーケンスを送信する*双方向ストリーミングRPC*。2つのストリームは独立して動作するため、クライアントとサーバーは好きな順序で読み書きできます。たとえば、サーバーはすべてのクライアントメッセージを受信するまで待ってからレスポンスを書き込むことも、メッセージを読み取ってからメッセージを書き込むことも、あるいは読み取りと書き込みの他の組み合わせを行うこともできます。各ストリーム内のメッセージの順序は保持されます。このタイプのメソッドを指定するには、リクエストとレスポンスの両方の前にstreamキーワードを配置します。
```
// Accepts a stream of RouteNotes sent while a route is being traversed,
// while receiving other RouteNotes (e.g. from other users).
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
```

.protoファイルには、サービスメソッドで使用されるすべてのリクエストとレスポンスタイプのProtocol Bufferメッセージタイプの定義も含まれています。たとえば、Pointメッセージタイプは次のとおりです。

// Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in
// the range +/- 180 degrees (inclusive).
message Point {
  int32 latitude = 1;
  int32 longitude = 2;
}

ファイルの先頭に`objc_class_prefix`オプションを追加することで、生成されるクラスに使用するプレフィックスを指定できます。例えば

option objc_class_prefix = "RTG";

クライアントコードの生成

次に、.protoサービス定義からgRPCクライアントインターフェースを生成する必要があります。これは、特別なgRPC Objective-Cプラグインを使用してProtocol Bufferコンパイラ（protoc）で行います。

簡単にするために、適切なプラグイン、入力、出力でprotocを実行し、生成されたファイルのコンパイル方法を記述するPodspecファイルを提供しています。このディレクトリ（examples/objective-c/route_guide）で実行するだけです

$ pod install

これは、生成されたライブラリをこのサンプルのXCodeプロジェクトにインストールする前に、次を実行します。

$ protoc -I ../../protos --objc_out=Pods/RouteGuide --objcgrpc_out=Pods/RouteGuide ../../protos/route_guide.proto

このコマンドを実行すると、Pods/RouteGuide/の下に次のファイルが生成されます。

生成されたメッセージクラスを宣言するヘッダーであるRouteGuide.pbobjc.h。
メッセージクラスの実装を含むRouteGuide.pbobjc.m。
生成されたサービスクラスを宣言するヘッダーである`RouteGuide.pbrpc.h`。
サービスクラスの実装を含む`RouteGuide.pbrpc.m`。

これらには以下が含まれます。

リクエストとレスポンスのメッセージタイプを入力、シリアル化、および取得するためのすべてのProtocol Bufferコード。
クライアントが`RouteGuide`サービスで定義されたメソッドを呼び出すことができる`RTGRouteGuide`というクラス。

提供されているPodspecファイルを使用して、他のprotoサービス定義からクライアントコードを生成することもできます。名前（ファイル名と一致）、バージョン、その他のメタデータを置き換えるだけです。

クライアントアプリケーションの作成

このセクションでは、`RouteGuide`サービスのObjective-Cクライアントの作成について説明します。完全なサンプルクライアントコードは、examples/objective-c/route_guide/ViewControllers.mにあります。

注意

アプリでは、保守性と可読性の理由から、すべてのビューコントローラーを1つのファイルに配置しないでください。ここでは、学習プロセスを簡素化するためにのみ行われています。

サービスオブジェクトの構築

サービスメソッドを呼び出すには、まずサービスオブジェクト、つまり生成された`RTGRouteGuide`クラスのインスタンスを作成する必要があります。クラスの指定されたイニシャライザは、接続先のサーバーのアドレスとポートを含む`NSString *`を想定しています。

#import <GRPCClient/GRPCCall+Tests.h>
#import <RouteGuide/RouteGuide.pbrpc.h>
#import <GRPCClient/GRPCTransport.h>

static NSString * const kHostAddress = @"localhost:50051";
...
GRPCMutableCallOptions *options = [[GRPCMutableCallOptions alloc] init];
options.transport = GRPCDefaultTransportImplList.core_insecure;

RTGRouteGuide *service = [[RTGRouteGuide alloc] initWithHost:kHostAddress callOptions:options];

サービスは安全でないトランスポートで構築されていることに注意してください。これは、クライアントのテストに使用するサーバーがTLSを使用していないためです。これは、開発マシン上でローカルに実行されるため問題ありません。ただし、最も一般的なケースは、インターネット上のgRPCサーバーに接続し、TLS経由でgRPCを実行することです。その場合、gRPCはデフォルトで安全なTLSトランスポートを使用するため、オプション`options.transport`を設定する必要はありません。

サービスメソッドの呼び出し

次に、サービスメソッドの呼び出し方法を見てみましょう。ご覧のとおり、これらのメソッドはすべて非同期であるため、UIのフリーズやOSによるアプリの強制終了を心配することなく、アプリのメインスレッドから呼び出すことができます。

単純RPC

シンプルなRPC GetFeature の呼び出しは、Cocoaの他の非同期メソッドの呼び出しと同じくらい簡単です。


RTGPoint *point = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

GRPCUnaryResponseHandler *handler =
    [[GRPCUnaryResponseHandler alloc] initWithResponseHandler:
        ^(RTGFeature *response, NSError *error) {
          if (response) {
            // Successful response received
          } else {
            // RPC error
          }
        }
                                        responseDispatchQueue:nil];

[[service getFeatureWithMessage:point responseHandler:handler callOptions:nil] start];

ご覧のとおり、リクエストプロトコルバッファオブジェクト（この場合は RTGPoint）を作成してデータを入力します。次に、サービスオブジェクトのメソッドを呼び出し、リクエストとレスポンス（またはRPCエラー）を処理するブロックを渡します。RPCが正常に完了すると、ハンドラブロックが nil のエラー引数で呼び出され、レスポンス引数からサーバーからのレスポンス情報を読み取ることができます。代わりに、RPCエラーが発生した場合、ハンドラブロックは nil のレスポンス引数で呼び出され、エラー引数から問題の詳細を読み取ることができます。

ストリーミングRPC

次に、ストリーミングメソッドを見てみましょう。ここでは、レスポンスストリーミングメソッド ListFeatures を呼び出します。これにより、クライアントアプリは地理的な RTGFeature のストリームを受信します。


- (void)didReceiveProtoMessage(GPBMessage *)message {
  if (message) {
    NSLog(@"Found feature at %@ called %@.", response.location, response.name);
  }
}

- (void)didCloseWithTrailingMetadata:(NSDictionary *)trailingMetadata error:(NSError *)error {
  if (error) {
    NSLog(@"RPC error: %@", error);
  }
}

- (void)execRequest {
  ...
  [[service listFeaturesWithMessage:rectangle responseHandler:self callOptions:nil] start];
}

レスポンスハンドラオブジェクトを提供する代わりに、ビューコントローラオブジェクト自体がレスポンスを処理することに注意してください。 didReceiveProtoMessage: メソッドは、メッセージを受信したときに呼び出されます。これは何度でも呼び出すことができます。 didCloseWithTrailingMetadata: メソッドは、呼び出しが完了し、サーバーからgRPCステータスを受信したとき（または呼び出し中にエラーが発生したとき）に呼び出されます。

リクエストストリーミングメソッド RecordRoute は、クライアントからの RTGPoint のストリームを予期します。このストリームは、呼び出しの開始後にgRPC呼び出しオブジェクトに書き込むことができます。

RTGPoint *point1 = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

RTGPoint *point2 = [RTGPoint message];
point.latitude = 40E7;
point.longitude = -74E7;

GRPCUnaryResponseHandler *handler =
    [[GRPCUnaryResponseHandler alloc] initWithResponseHandler:
        ^(RTGRouteSummary *response, NSError *error) {
            if (response) {
              NSLog(@"Finished trip with %i points", response.pointCount);
              NSLog(@"Passed %i features", response.featureCount);
              NSLog(@"Travelled %i meters", response.distance);
              NSLog(@"It took %i seconds", response.elapsedTime);
            } else {
              NSLog(@"RPC error: %@", error);
            }
        }
                                        responseDispatchQueue:nil];
GRPCStreamingProtoCall *call =
    [service recordRouteWithResponseHandler:handler callOptions:nil];
[call start];
[call writeMessage:point1];
[call writeMessage:point2];
[call finish];

gRPC呼び出しオブジェクトはリクエストストリームの終わりを認識しないため、ユーザーはリクエストストリームが完了したときに finish: メソッドを呼び出す必要があることに注意してください。

最後に、双方向ストリーミングRPC RouteChat() を見てみましょう。双方向ストリーミングRPCを呼び出す方法は、リクエストストリーミングRPCとレスポンスストリーミングRPCの呼び出し方法を組み合わせたものです。


- (void)didReceiveProtoMessage(GPBMessage *)message {
  RTGRouteNote *note = (RTGRouteNote *)message;
  if (note) {
    NSLog(@"Got message %@ at %@", note.message, note.location);
  }
}

- (void)didCloseWithTrailingMetadata:(NSDictionary *)trailingMetadata error:(NSError *)error {
  if (error) {
    NSLog(@"RPC error: %@", error);
  } else {
    NSLog(@"Chat ended.");
  }
}

- (void)execRequest {
  ...
  GRPCStreamingProtoCall *call =
      [service routeChatWithResponseHandler:self callOptions:nil];
  [call start];
  [call writeMessage:note1];
  ...
  [call writeMessage:noteN];
  [call finish];
}

最終更新日：2023年2月16日: プロトコルバッファドキュメントのURLを更新 (#1092) (852a744)

ページソースを表示このページを編集子ページを作成ドキュメントの問題を作成プロジェクトの問題を作成