mirror of https://github.com/grpc/grpc.io.git
295 lines
15 KiB
HTML
295 lines
15 KiB
HTML
|
||
|
||
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
||
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
|
||
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400" rel="stylesheet">
|
||
<link rel="stylesheet" type="text/css" href="/css/style.css">
|
||
<title>
|
||
Guides – gRPC
|
||
</title>
|
||
|
||
|
||
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png" sizes="180x180">
|
||
<link rel="icon" type="image/png" href="/favicons/android-chrome-192x192.png" sizes="192x192" >
|
||
<link rel="icon" type="image/png" href="/favicons/favicon-32x32.png" sizes="32x32">
|
||
<link rel="icon" type="image/png" href="/favicons/favicon-16x16.png" sizes="16x16">
|
||
<link rel="manifest" href="/favicons/manifest.json">
|
||
<link rel="mask-icon" href="/favicons/safari-pinned-tab.svg" color="#2DA6B0">
|
||
<meta name="msapplication-TileColor" content="#ffffff">
|
||
<meta name="msapplication-TileImage" content="/favicons/mstile-150x150.png">
|
||
|
||
|
||
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-60127042-1"></script>
|
||
<script>
|
||
window.dataLayer = window.dataLayer || [];
|
||
function gtag(){dataLayer.push(arguments);}
|
||
gtag('js', new Date());
|
||
|
||
gtag('config', 'UA-60127042-1');
|
||
</script>
|
||
|
||
</head>
|
||
<body>
|
||
<div id="landing-content">
|
||
<div class="row">
|
||
<div class="topbannersub">
|
||
<nav class="navbar navbar-expand-md navbar-dark topnav">
|
||
<a class="navbar-brand" href="https://cjyabraham.github.io/">
|
||
<img src="https://cjyabraham.github.io/img/grpc-logo.png" width="114" height="50">
|
||
</a>
|
||
|
||
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
|
||
<span class="navbar-toggler-icon"></span>
|
||
</button>
|
||
|
||
<div class="topnav, collapse navbar-collapse" id="navbarSupportedContent" style="float:right !important">
|
||
<ul class="navbar-nav ml-auto">
|
||
<li class="nav-item ">
|
||
<a class="nav-link" href="https://cjyabraham.github.io/about/">About</a>
|
||
</li>
|
||
<li class="nav-item dropdown active">
|
||
<a class="nav-link dropdown-toggle" href="https://cjyabraham.github.io/docs/" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
|
||
Docs
|
||
</a>
|
||
|
||
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
|
||
|
||
|
||
<a class="dropdown-item" href="/docs">
|
||
Overview
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/quickstart/">
|
||
Quick Start
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/guides/">
|
||
Guides
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/tutorials/">
|
||
Tutorials
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/reference/">
|
||
Reference
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/samples/">
|
||
Samples
|
||
</a>
|
||
|
||
|
||
<a class="dropdown-item" href="/docs/talks">
|
||
Presentations
|
||
</a>
|
||
|
||
</div>
|
||
</li>
|
||
<li class="nav-item ">
|
||
<a class="nav-link" href="/blog">
|
||
Blog
|
||
</a>
|
||
</li>
|
||
<li class="nav-item ">
|
||
<a class="nav-link" href="/community">Community</a>
|
||
</li>
|
||
<li class="nav-item">
|
||
<a class="nav-link" href="https://packages.grpc.io/">
|
||
Packages
|
||
</a>
|
||
</li>
|
||
<li class="nav-item ">
|
||
<a class="nav-link" href="https://cjyabraham.github.io/faq/">FAQ</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
|
||
|
||
|
||
|
||
|
||
<div class="headertext">Documentation</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="subnav d-none d-md-block">
|
||
<a href="https://cjyabraham.github.io/docs/" >Overview</a>
|
||
| <a href="https://cjyabraham.github.io/docs/quickstart/" >Quick Start</a>
|
||
| <a href="https://cjyabraham.github.io/docs/guides/" class="active">Guides</a>
|
||
| <a href="https://cjyabraham.github.io/docs/tutorials/" >Tutorials</a>
|
||
| <a href="https://cjyabraham.github.io/docs/reference/" >Reference</a>
|
||
| <a href="https://cjyabraham.github.io/docs/samples/" >Samples</a>
|
||
| <a href="https://cjyabraham.github.io/docs/talks/" >Presentations</a>
|
||
</div>
|
||
|
||
|
||
<div class="quickstartcols">
|
||
|
||
<div class="quickstartcol1">
|
||
|
||
<h8>Guides</h8>
|
||
|
||
|
||
<a href="/docs/guides/" class="active">
|
||
What is gRPC?
|
||
</a>
|
||
|
||
|
||
<a href="/docs/guides/concepts/">
|
||
gRPC Concepts
|
||
</a>
|
||
|
||
|
||
<a href="/docs/guides/auth/">
|
||
Authentication
|
||
</a>
|
||
|
||
|
||
<a href="/docs/guides/error/">
|
||
Error handling and debugging
|
||
</a>
|
||
|
||
|
||
<a href="/docs/guides/benchmarking/">
|
||
Benchmarking
|
||
</a>
|
||
|
||
|
||
<a href="https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md">
|
||
gRPC Wire Format
|
||
</a>
|
||
|
||
|
||
<h8 style="margin-top:25%">Related Guides</h8>
|
||
<a href="https://developers.google.com/protocol-buffers/docs/overview">Protocol Buffers</a>
|
||
</div>
|
||
|
||
<div class="quickstartcol2" style="margin-top:4%">
|
||
<h3 style="margin-top:0px;">
|
||
Guides
|
||
</h3>
|
||
|
||
|
||
|
||
<p>This document introduces you to gRPC and protocol buffers. gRPC can use
|
||
protocol buffers as both its Interface Definition Language (IDL) and as its underlying message
|
||
interchange format. If you’re new to gRPC and/or protocol buffers, read this!
|
||
If you just want to dive in and see gRPC in action first,
|
||
see our <a href="../quickstart">Quick Starts</a>.</p>
|
||
|
||
<div id="toc" class="toc mobile-toc"></div>
|
||
|
||
<h3 id="overview">Overview</h3>
|
||
|
||
<p>In gRPC a client application can directly call methods on a server application on a different machine as if it was a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.</p>
|
||
|
||
<p><img src="../../img/landing-2.svg" alt="Concept Diagram" /></p>
|
||
|
||
<p>gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC’s supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. In addition, the latest Google APIs will have gRPC versions of their interfaces, letting you easily build Google functionality into your applications.</p>
|
||
|
||
<h3 id="working-with-protocol-buffers">Working with Protocol Buffers</h3>
|
||
|
||
<p>By default gRPC uses <a href="https://developers.google.com/protocol-buffers/docs/overview">protocol buffers</a>, Google’s
|
||
mature open source mechanism for serializing structured data (although it
|
||
can be used with other data formats such as JSON). Here’s a quick intro to how
|
||
it works. If you’re already familiar with protocol buffers, feel free to skip
|
||
ahead to the next section.</p>
|
||
|
||
<p>The first step when working with protocol buffers is to define the structure
|
||
for the data you want to serialize in a <em>proto file</em>: this is an ordinary text
|
||
file with a <code>.proto</code> extension. Protocol buffer data is structured as
|
||
<em>messages</em>, where each message is a small logical record of information
|
||
containing a series of name-value pairs called <em>fields</em>. Here’s a simple
|
||
example:</p>
|
||
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-proto" data-lang="proto"><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">Person</span> {<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">int32</span> id <span style="color:#f92672">=</span> <span style="color:#ae81ff">2</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">bool</span> has_ponycopter <span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span>}</code></pre></div>
|
||
<p>Then, once you’ve specified your data structures, you use the protocol buffer
|
||
compiler <code>protoc</code> to generate data access classes in your preferred language(s)
|
||
from your proto definition. These provide simple accessors for each field
|
||
(like <code>name()</code> and <code>set_name()</code>) as well as methods to serialize/parse
|
||
the whole structure to/from raw bytes – so, for instance, if your chosen
|
||
language is C++, running the compiler on the above example will generate a
|
||
class called <code>Person</code>. You can then use this class in your application to
|
||
populate, serialize, and retrieve Person protocol buffer messages.</p>
|
||
|
||
<p>As you’ll see in more detail in our examples, you define gRPC services
|
||
in ordinary proto files, with RPC method parameters and return types specified as
|
||
protocol buffer messages:</p>
|
||
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-proto" data-lang="proto"><span style="color:#75715e">// The greeter service definition.
|
||
</span><span style="color:#75715e"></span><span style="color:#66d9ef">service</span> Greeter {<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#75715e">// Sends a greeting
|
||
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">rpc</span> SayHello (HelloRequest) <span style="color:#66d9ef">returns</span> (HelloReply) {}<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The request message containing the user's name.
|
||
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloRequest</span> {<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span>}<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span><span style="color:#75715e">// The response message containing the greetings
|
||
</span><span style="color:#75715e"></span><span style="color:#66d9ef">message</span> <span style="color:#a6e22e">HelloReply</span> {<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span> <span style="color:#66d9ef">string</span> <span style="color:#66d9ef">message</span> <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;<span style="color:#960050;background-color:#1e0010">
|
||
</span><span style="color:#960050;background-color:#1e0010"></span>}</code></pre></div>
|
||
<p>gRPC also uses <code>protoc</code> with a special gRPC plugin to
|
||
generate code from your proto file. However, with the gRPC plugin, you get
|
||
generated gRPC client and server code, as well as the regular protocol buffer
|
||
code for populating, serializing, and retrieving your message types. We’ll
|
||
look at this example in more detail below.</p>
|
||
|
||
<p>You can find out lots more about protocol buffers in the <a href="https://developers.google.com/protocol-buffers/docs/overview">Protocol Buffers
|
||
documentation</a>,
|
||
and find out how to get and install <code>protoc</code> with gRPC plugins in your chosen
|
||
language’s Quickstart.</p>
|
||
|
||
<h4 id="protocol-buffer-versions">Protocol buffer versions</h4>
|
||
|
||
<p>While protocol buffers have been available for open source users for some
|
||
time, our examples use a new flavor of protocol buffers called proto3, which
|
||
has a slightly simplified syntax, some useful new features, and supports
|
||
lots more languages. This is currently available in Java, C++, Python,
|
||
Objective-C, C#, a lite-runtime (Android Java), Ruby, and JavaScript from the
|
||
<a href="https://github.com/google/protobuf/releases">protocol buffers GitHub repo</a>,
|
||
as well as a Go language generator from the <a href="https://github.com/golang/protobuf">golang/protobuf GitHub
|
||
repo</a>, with more languages
|
||
in development. You can find out more in the <a href="https://developers.google.com/protocol-buffers/docs/proto3">proto3 language
|
||
guide</a> and the
|
||
<a href="https://developers.google.com/protocol-buffers/docs/reference/overview">reference documentation</a>
|
||
available for each language. The reference documentation also includes a
|
||
<a href="https://developers.google.com/protocol-buffers/docs/reference/proto3-spec">formal specification</a>
|
||
for the <code>.proto</code> file format.</p>
|
||
|
||
<p>In general, while you can use proto2 (the current default protocol buffers
|
||
version), we recommend that you use proto3 with gRPC as it lets you use the
|
||
full range of gRPC-supported languages, as well as avoiding compatibility
|
||
issues with proto2 clients talking to proto3 servers and vice versa.</p>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
|
||
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
|
||
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
|
||
|
||
</body>
|
||
</html>
|