How to Call Google APIs: RPC Edition
For many developers, the easiest way to call a Google API is with one of our client libraries. But occasionally someone may prefer to make API calls directly — perhaps from a language or environment that we don’t support or using a different networking library or tool. Here we’ll show you how to do it.
This page focuses on calling Google APIs directly using their underlying RPC interfaces. Most Google APIs are also available as REST services. For that, see How to Call Google APIs, REST Edition.
What you’ll need
An API definition
Most Google APIs are designed as RPC APIs using Protocol Buffers. The Protocol Buffers definitions of public Google APIs are hosted on GitHub in the googleapis/googleapis repository.
For these examples, we’ll use the Cloud Natural Language API, which is defined by google/cloud/language/v1/language_service.proto. The RPC details are documented online in the Google Cloud Natural Language API reference. We’ll call the AnalyzeEntities API, which takes a block of text as input and returns a list of names and nouns that it finds in the text along with some interesting properties of each entity.
Protocol Buffers
For all Google RPC APIs, the messages that are sent and received using the Protocol Buffers encoding, and the definitive descriptions of these APIs are written in the Protocol Buffers Language.
To compile Protocol Buffer Language files, you’ll need protoc , the Protocol Buffer compiler. You can download protoc from the google/protobuf release page on GitHub (look for the protoc release for your machine architecture, e.g. protoc-3.6.0-linux-x86_64.zip ) or build it from source (this will take a while).
You’ll probably also need a code generation plugin for the language that you’re using. Plugins are standalone executables written in many different languages, and the plugin interface is defined in the plugin.proto file. Here are some plugins that we have used:
For a list of Google-supported languages, see the Protocol Buffers API Reference.
Making RPC API requests
gRPC is the recommended way to call Google RPC APIs. gRPC support is typically provided by additional protoc plugins that generate code for API clients and servers. This code uses lower-level primitives that send messages using gRPC’s HTTP/2-based messaging system, which supports request multiplexing, streaming APIs, and advanced flow control. To learn more about working with gRPC, visit grpc.io/docs.
If gRPC support is unavailable, Google APIs can also be called using HTTP/1.1 or later using the fallback protocol described in the next section.
Authentication
To use Google APIs, a client needs to authenticate with an API key or an OAuth token. For more information, see the Google Cloud Authentication Overview.
API keys can be obtained from the Google Cloud Console > Credentials page. OAuth tokens can be obtained by OAuth 2 clients and libraries. For a sample command-line client, see the oauth2l on GitHub.
gRPC Fallback (Experimental)
Along with gRPC, most Google APIs support a simple fallback protocol that uses Protocol Buffers (protobuf) over HTTP. It allows clients to call Google APIs directly, often using standard library functions.
This protocol uses fixed URLs to specify the RPC endpoints, and passes request/response messages as HTTP request/response body using HTTP POST. It uses normal HTTP headers to pass the RPC metadata, such as System Parameters.
RPC URLs have the following format:
BaseUrl. This is the base URL published by service owners, either via documentation or service discovery. For most Google APIs, the BaseUrl looks like https://language.googleapis.com/$rpc (experimental: this format may change in the future). The base address can be found in the API reference documentation where it is identified as the Service name . For this example, language.googleapis.com is found in the Google Cloud Natural Language API Reference.
Service. This is the fully qualified protobuf service name, such as google.cloud.language.v1.LanguageService . In this case, google.cloud.language.v1 is the package name in google/cloud/language/v1/language_service.proto and LanguageService is the name of the service section found in this file.
Method. This is the protobuf rpc name, such as AnnotateText .
Requests
RPC request messages are serialized and sent as the HTTP request body. For the server to handle the request properly, the client must set several HTTP request headers:
Content-Type. The request message format is specified by the Content-Type header and must be application/x-protobuf .
X-Goog-Api-Key. This specifies a valid Google API key. It is optional if the Authorization header is used.
Authorization. This specifies a valid Google OAuth access token in the format of Bearer
Responses
For successful requests, the HTTP status code is 200 and the HTTP response body contains the serialized RPC response message. For unsuccessful requests, the HTTP status code is the HTTP mapping for google.rpc.Code and the HTTP response body contains a serialized google.rpc.Status message. For details, see Errors in the API Design Guide.
The HTTP response contains at least the following headers:
- Content-Type. This specifies the response serialization format. For normal responses and server errors, this will be application/x-protobuf . Different values can be returned for network errors, such as when a message is rejected by a network proxy. All such errors will be accompanied by appropriate HTTP status codes.
Examples
To illustrate how easily the gRPC fallback protocol can be used to call Google RPC APIs, we’ve written a few examples. Each is as basic as possible — using standard library functions wherever possible and commonly-used Protocol Buffer support code. If you write one in a different language, send us a pull request!
1. RPC ?
RPC (Remote Procedure Call) — это интерфейс между клиентом (Metamask, Frame, Rabbit, …) и блокчейном, позволяющий клиенту обмениваться данными с блокчейном.
Легко понять, что третьей стороне, выбранной для выполнения этой роли, необходимо доверять. Самодельный” RPC, найденный в интернете, может скрывать атаку “человек посередине”, то есть располагаться между пользователем и блокчейном, чтобы изменить запрос, отправленный пользователем… Чего мы все очень хотим избежать!
2. Выбор поставщика
У нас есть несколько вариантов, но в этом руководстве я остановлюсь на Алхимии. Бесплатное предложение отлично подходит для личного пользования:
Через это предложение наш клиент сможет получить доступ к блокчейну 300M раз (транзакции, аутентификации, запросы цен, отображения NFT, …), что более чем достаточно. Для примера, я трачу 1/3 своего дня на web3 и не превышаю 100M взаимодействий.
Прямым конкурентом Alchemy является Infura, которая не так давно была связана с делом о “принудительном исключении” пользователей, проживающих в Венесуэле. Естественно, я не выбрал Infura…
3. Создание RPC
Предварительное условие: Вам потребуется действующий адрес электронной почты.
- Перейти на сайт www.alchemy.com
- На главной странице нажмите на кнопку “LOGIN”
3. Мы создадим учетную запись, нажмите “Регистрация”
4. Введите свои данные и нажмите на кнопку “Зарегистрироваться”
5. Вам было отправлено письмо с подтверждением. Откройте его и нажмите на “VERIFY EMAIL”
6. Выберите свою экосистему. В моем случае я хочу создать RPC для использования на Polygon (совместимый с EVM / Ethereum), поэтому я выберу Ethereum. Нажмите на кнопку “Начать работу”
7. Заполните и создайте свое первое приложение. В нашем случае мы хотим создать RPC для личного пользования на блокчейне Polygon. Нажмите на кнопку “Создать приложение”
8. Выберите свое предложение. В нашем случае, как мы уже видели ранее, мы начнем с бесплатного предложения. Этого достаточно для личного пользования. Выберите предложение “FREE FOREVER” и нажмите “Продолжить”
9. Вам не нужно добавлять способ оплаты, я предлагаю вам нажать “Пока пропустить”. Как уже упоминалось, добавление способа оплаты добавляет 1М взаимодействий в месяц с блокчейном. У нас уже есть 300 миллионов…
10. Твитить или не твитить свою реферальную ссылку… По вашему желанию. Я лично нажму на “Пока пропустить”
11. Мы выберем “Capped Capacity”, так как не собираемся платить за свой личный CPP. Нажмите кнопку “Continue”
12. Вы можете заполнить информацию о том, как вы узнали об Алхимии, и нажать кнопку “Let’s Go”
Вы должны попасть на эту страницу
Поздравляю! Ваш персональный CPP наконец-то создан!
4. Использование этого RPC с Metamask
Напомним, что мы создали персональный RPC для использования на блокчейне Polygon.
1- В Metamask щелкните 1 на вашей сети и 2 на добавить сеть
2- Заполните следующие параметры
Network Name : Polygon Alchemy
Chain ID : 137
Currency Symbol : MATIC
Block Explorer URL : https://polygonscan.com
New RPC URL : Вы скопируете/вставите URL RPC, предоставленный Alchemy. Этот URL включает ваш API-ключ (идентификатор для Alchemy). С ним можно ознакомиться здесь :
3- В разделе Metamask выберите только что созданную сеть
И это все! Наконец-то вы перешли на свой личный CPP со всеми вытекающими отсюда преимуществами (больше никаких ошибок из-за перегруженных общественных CPP, …).
Rpc url что это
Help us improve
Please mention the error details that you have encountered with
you can also get in touch with us : contact@dapp-world.com
Founder at DApp World
Introduction
Like web3.js we can use web3.py to communicate with blockchain. This smartbook will be an introduction to web3.py. We will simply transafer some test ethers using web3.py that way we will get to know about web3.ps’s working as it is little different that web3.js. You can refer this smartbook which did same interaction with blockchain but with implementation of web3.js library.
Configuration
1. Getting rpc url
RPC url is required for our program to interact with a blockchain network. You can check different methods to connect through providers in this smartbook.
For this example provder we will be using is Infura via http. All we have to do is create an account and generate a project which will provide us with rpc url for created project’s api key.
2. Getting test tokens
You can get test tokens from ropsten faucet. Enter your address and click on submit.
3. Web3 Installation
pip is the most used pacakage management system for python so we will be using it to install our web3 library using following command
Transfer Program
1. Initialise Variables
Let’s create a web3 instace with http provider.
2. Transaction Object
Transaction object which we will be creating require following parameters
- nonce : It is a random number required to process transactions to avoid repeatation of transaction
- to : Receiver’s address
- value : Amount to be sent in wei (1 ether = 10^18 wei)
- gas : Gas amount in number
- gasPrice : Gas fees in gwei
We will be obtaining nonce with the help of getTransactionCount method.
Note that : the transaction object that we created here is a python dictionary.
2. Sign Transaction
This function will return a transaction that’s been signed by the node’s private key (i.e we have private key and a rpc node), but not yet submitted.
Syntax : web3.eth.account.sign_transaction( Tx Object, Private_Key )
Parameters :
- Tx Object — The transaction data/object to sign.
- Private_Key — Private key of a address to sign a transaction with.
Returns : Signed transaction object is returned.
Implementation :
2. Send Signed Transaction
This function will send a signed and serialized transaction and will returns the transaction hash as a HexBytes object.
Syntax : web3.eth.send_raw_transaction(signed_tx.rawTransaction)
Parameters :
- Raw_Transaction — Raw transaction which we got from sign transaction method.
Returns : Transaction hash as a HexBytes object.
Implementation :
Here we will get transaction hash in the hex byte format we need to convert it into hex format.
This is how we can send our transaction on the ethereum network using web3.py
Клиент-серверное и межсервисное взаимодействие: разбираемся в REST, GraphQL, RPC и WebSocket
Привет всем! Меня зовут Андрей, и я разработчик. На своей практике я успел столкнуться с разными протоколами. И, конечно же, были холивары в команде — какой и почему выбрать. Адепты подхода REST спорят с GraphQL-щиками. А поклонники gRPC тихо смеются над ними. Давайте все разложим по полочкам.
В зависимости от системы, ограничений и личных предпочтений команды понадобятся самые разные способы общения и передачи данных. REST, GraphQL, RPC и другие — сегодня разберемся во всем многообразии протоколов, где и зачем они используются.
Что такое протокол?
Простыми словами, это общепринятый способ / формат общения систем между собой. Протоколов довольно много — протоколы общения с устройствами (USB, Bluetooth), протоколы межпроцессного взаимодействия (IPC), протоколы взаимодействия с удаленными компьютерами (SSH, FTP), протоколы отправки и получения почты (SMTP, POP3). Мы будем говорить только о веб-протоколах — способах общения фронтенда (мобильный или веб-клиент) с бэкендом или сервисов между собой.
Большинство веб-протоколов работают поверх HTTP. Прежде чем говорить о других протоколах, расскажем, на основе чего они все строятся и работают:
Примечание: мы не будем разбирать модель TCP/IP, на которой работает сеть Интернета. Для рассмотрения протоколов передачи данных достаточно понимать, что HTTP работает поверх TCP/IP. Если вам стало интересно, то по ссылке можете углубиться в эту тему.
Введение: как работает протокол HTTP
В разработке основным протоколом передачи данных является HTTP. Он относится к прикладным протоколам и работает поверх других протоколов сетевого стека. HTTP — это простой текстовый протокол для передачи любого контента. Изначально разработан для передачи HTML-файлов (в те времена, когда HTML был языком разметки научной и технической документации в CERN).
Как правило, в вебе мы используем надстройки поверх протокола. HTTP работает поверх TCP — один из транспортных протоколов, который определяет, как данные будут передаваться от компьютера к компьютеру. В случае с TCP «отправитель» будет ожидать ответа, что «получатель» принял пакет, прежде чем отправить следующий. Если «отправитель» не дождался подтверждения — отправит пакет еще раз.
Для передачи данных используются HTTP-пакеты. Сам пакет в HTTP представляет собой текстовое сообщение со следующей структурой:
<HTTP-метод> <Путь ресурса> HTTP/1.1
HTTP-метод — это глагол, который определяет, какую операцию мы хотим выполнить (GET, POST, PUT и т.д.);
Путь — URL до необходимого нам ресурса;
Версия протокола — чаще всего указывается HTTP/1.1;
Заголовки — дополнительные параметры запроса, которые нужны серверу;
Тело запроса — данные, которые мы хотим передать.
Например, выполним POST-запрос на создание пользователя Вася, который не является администратором в системе. Причем укажем, что данные передаются в формате JSON, а ответ мы ожидаем на русском языке.
Эти термины пригодятся, когда мы будем говорить о других протоколах. Без контекста HTTP непонятно, что такое пути, заголовки, тело и статусы ответов. Часть протоколов использует все, а часть нет.
Начнем мы с одного из старейших подходов в вебе — REST, который использует все возможности HTTP. Потом пройдемся по GraphQL, которому предрекали судьбу полностью вытеснить REST. Далее посмотрим на семейство RPC-протоколов. И WebSocket — альтернативный подход во взаимодействии с бэкендом, ориентированный на постоянную связь клиента и сервера.
REST — Representational state transfer — архитектурный подход, который описывает набор правил, как организовать общение систем. У данного подхода есть ряд требований — отсутствие состояния, единообразие интерфейсов. В простом понимании это URI, который описывает, что за ресурс мы запрашиваем: список элементов или один элемент. Кроме того, используются HTTP-глаголы или HTTP-методы — какие действия мы произведем с ресурсом.
Методов достаточно много. Как правило, мы имеем дело с:
POST /users для создания нового пользователя;
GET /users для получения списка пользователей;
PUT или PATCH /users/1 для изменения пользователя;
DELETE /users/1 для удаления.
В ответе от сервера мы получаем запрошенный ресурс / сообщение об ошибке и трехзначный код ответа. Код ответа показывает, что произошло с запросом пользователя и что, в случае ошибки, пошло не по плану. Например:
200 – запрос выполнен успешно;
401 – необходимо авторизоваться;
404 – ресурс не найден;
505 – сервер временно недоступен.
С приходом JSON, как основного формата общения, требования к системам начали расти. Росли и требования к REST. Так появилась спецификация HATEOAS — дополнение требований. Теперь вместе с возвращаемым ресурсом мы можем получить информацию о том, какой набор действий предоставлен пользователю с этими ресурсами. Так, если мы делаем запрос GET /users , то получим список пользователей и:
количество страниц, на которые разбит этот список;
ссылки на предыдущую и следующую страницы;
в каждом элементе списка будет ссылка на конкретного пользователя.
Но и эта система получила дальнейшее развитие в лице JSON:API. Подход в свое время получил приз зрительских симпатий в категории «Название, которое максимально неудобно гуглить». Изначально этот формат использовался во фреймворке Ember для общения с бэкендом. Потом был опубликован отдельной спецификацией:
в JSON:API была добавлена группировка GET-параметров по смыслу. Вместо page_size и page_number предлагалось использовать page[size] и page[number] или page[offset] ;
добавлен единый формат самих ресурсов:
поддержка зависимых ресурсов, что помогало получать несколько связанных ресурсов в одном запросе, а не частями. Пользователя можно получить вместе с его постами, а посты — с комментариями.
Так REST развился до современного состояния. Решения на основе HATEOAS или JSON:API используются не везде и не всегда. Пока что REST-подход остается наиболее распространенным в современном вебе. Хотя в один момент даже начали говорить о его скорой смерти.
GraphQL
В 2015 году Facebook опубликовал свой новый язык общения фронтенда с бэкендом. Уже к 2019 году некоторые веб-разработчики начали говорить, что GraphQL вытеснит REST.
GraphQL больше язык запросов, чем протокол. Но его стоит рассматривать как протокол. Так как с его помощью предлагается общаться с бэкендом.
В отличие от REST, у нас есть единая точка доступа к приложению — /graphql . На нее мы отправляем все наши запросы. Язык позволяет писать запросы к ресурсам в виде графа зависимостей, где зависимостью может быть поле или связанная сущность:
Мы можем сами определять, как запрашивать каждый ресурс — это считается преимуществом над REST для клиента. Кроме того, у GraphQL есть своя система типов, схема описания ресурсов и возможность добавления параметров в запросы. Сам GraphQL может служить прослойкой для обращения к другим сервисам и агрегации данных.
Как и любой формат общения, GraphQL вводит ряд понятий:
обработчик (resolver) — функция, отвечающая за выдачу данных по запросу;
схема (schema) — описание структуры данных в рамках GraphQL;
мутация (mutation) — тот же обработчик, только на изменение данных.
Авторы GraphQL позиционируют его как protocol-agnostic, то есть он не привязан к конкретному протоколу. Это позволяет использовать его и поверх HTTP, и поверх WebSocket, о котором пойдет речь дальше.
Рекомендую прочитать материал REST API vs GraphQL. В нем разобрано, что действительно стоит за их сравнением, нужно ли срочно заменить REST на GraphQL, и как подойти с головой при выборе архитектуры общения фронта и бэка.
У семейства протоколов RPC (Remote Procedure Call) свой отличительный подход — удаленный вызов процедур. В отличие от REST, одна точка входа, и телом запроса определяется, какой ресурс или какое действие будет выполнено. Реализаций подхода не так много. Главным образом они различаются форматом передачи данных — XML, JSON или бинарный.
XML-RPC и SOAP
XML-RPC изначально был разработан Microsoft в конце 90-х годов. Это текстовый протокол, в изначальном виде довольно прост в освоении. Единственная проблема этого формата — это сам XML (eXtensible Markup Language). XML, как формат передачи данных, довольно избыточен. В первую очередь, из-за открывающих и закрывающих тегов. У HTML в каком-то смысле та же проблема, но ничего другого для верстки не существует.
Позже Microsoft разработали еще один протокол, который стал расширением XML-RPC — SOAP (Simple Object Access Protocol). У него более строгая структура, много ограничений и требований. Сам протокол может работать поверх множества сетевых протоколов – SMTP, FTP и тд.
Сейчас SOAP используется для общений между сервисами (в основном с 1С) и для отправки SMS. Некоторые сервисы вроде интернет-магазинов до сих пор используют его для внутренних нужд — для SOAP один раз описывается схема передачи данных, дальше большинство SOAP-клиентов сами могут сформировать запрос и ответ без дополнительных действий со стороны разработчика.
JSON-RPC
JSON-RPC — это протокол семейства RPC, у которого в качестве формата передачи данных используется JSON. Типичный запрос выглядит так:
, где method — это имя вызываемой процедуры; params — список аргументов процедуры; id — уникальный идентификатор запроса, который генерируется запрашивающей стороной.
Несмотря на простоту и внешнее удобство, не получил популярности. В том числе из-за REST API с поддержкой JSON в качестве формата передачи данных.
Но не так давно в React сообществе появился новый формат общения между разными частями приложения, построенного на фреймворке Next.js – tRPC. Является версией JSON-RPC с поддержкой типизации из TypeScript. Протокол относительно молодой, основное применение и развитие происходит пока только внутри React (Next.js) сообщества. Но внимания заслуживает.
В остальном же JSON-RPC популярность не снискал и практически не используется.
gRPC — это бинарный протокол, т.е. данные передаются в бинарном виде, а не в виде текста. Разработан в Google и изначально использовался только для унификации взаимодействий между сервисов внутри самой компании. В 2016 году был выпущен в публичный доступ.
Для кодирования и декодирования сообщений используется собственный протокол сериализации Protobuf (Protocol Buffers). Максимально похожий на структуры из языка Си. Из плюсов Protobuf выделяют компактность, скорость сериализации и десериализации (особенно в сравнении с XML-форматами). Для описания формата сообщений и обработчиков пишутся *.proto файлы. Потом эти файлы компилируются в язык, на котором пишется приложение — Java, Python, PHP, JavaScript, Go и многие другие. Стоит отметить, что в Go-среде получил наибольшее распространение.
Главным ограничением протокола является, что он работает поверх HTTP/2. Это полностью (на данный момент) исключает его использование в браузерах. Поэтому gRPC — протокол исключительно для общения сервисов на стороне бэкенда. Протокол очень популярен. Поэтому, если вы не столкнетесь с ним в первый год работы, иметь о нем представление будет полезно.
WebSocket
WebSocket — это протокол двусторонней связи для постоянного обмена сообщениями клиента и сервера. Как и HTTP, WebSocket работает поверх TCP. Но вместо периодического соединения формата «запрос – ответ», держит постоянное соединение с сервером. Поэтому сервер всегда знает конкретного клиента «в лицо» и может отправить ему данные без дополнительного запроса. Например, используется для систем оповещений и чатов браузерных игр.
До появления полноценного стандарта подобные задачи решались двумя способами. Первый, периодические запросы «у меня есть новые сообщения» — но этот способ фактически мертв. Второй, Long-polling запросы — сервер не ограничен по времени, в течении которого он должен отдать ответ. Когда сервер получает запрос, он ответит на него, когда данные будут доступны для отправки. А браузер, в свою очередь, как только получит эти данные, сразу же делает новый запрос. Для конечного пользователя это выглядит как постоянное соединение с сервером.
В отличие от gRPC, вам не нужно будет изучать какой-то специфический формат обмена данными. WebSocket использует свой собственный бинарный формат, внутри которого вы можете передавать что угодно в удобной для вашего приложения форме.
Общение через WebSocket может быть реализовано по принципам REST — HTTP-метод + ресурс + тело запроса. Или реализовано, как JSON-RPC — имя процедуры + список параметров. Либо вовсе использовать GraphQL — называется «подпиской» (subscription).
Самое частое применение WebSocket — real-time чаты. Новое сообщение получатель видит, когда сервер рассылает сообщения всем адресатам, а не когда запрашивает сам. Библиотеки для WebSocket-сервера существуют почти для всех языков и их фреймворков. Вопрос будет только в выборе самого популярного и/или удобного лично для вас.
Отлично! Что с этим теперь делать, и где использовать?
Если вы начинающий специалист, изучите сначала REST. Не важно, как вы себя позиционируете — бэкенд, фронтенд, мобайл, аналитик или тестировщик. REST — самый распространенный. Поэтому знать его принципы обязательно.
Потом, если вы занимаетесь бэкендом, посмотрите в сторону gRPC. Сейчас он все чаще появляется в проектах и пытается вытеснить REST в общении сервисов. И посмотрите GraphQL, особенно если занимаетесь фронтендом. Он здесь становится все популярнее.
Дальше задайте себе вопрос: «Что лучше решает задачу?». Большинство задач может решить REST. Задачи по быстрому межсервисному взаимодействию возьмет на себя gRPC. Оставшуюся часть могут покрыть SOAP или GraphQL. Например, SOAP будет задействован в общении со складскими системами — 1С и похожие. С помощью GraphQL на клиентской стороне будут запрашиваться данные о профиле пользователя. В остальном дело будет стоять за командой, руководителем и вашим собственным выбором.
Не все из этого вы будете использовать в работе каждый день. Но я рекомендую делать выбор в пользу того или иного протокола с пониманием особенностей и нюансов самих протоколов, бизнес-задач проекта и возможностей вашей команды.