Как делать запросы в GraphQL
Основы GraphQL, запросы и многое другое.
Who's this for ? - You need to learn how to query graphQL fast, maybe because your new project or prospective job needs you to. - You are comfortable with traditional rest APIs but can't get into graphQL. - You want Python/Javascript implementation examples. - You are curios about GraphQL. NOTE: This is not the right tutorial if you want to write or serve graphs via an API since I won't be covering that aspect, although I think it helps if you understand how to consume graphs first and some general theory, so this will also help you.
Что это ?
В целом, где-то в базе данных есть данные, и их можно сделать общедоступными / раскрыть через API. традиционно вам будет предоставлена конечная точка и синтаксис для запроса через REST, что-то вроде api.yummysnacks/list_snacks , затем вы используете какую-нибудь библиотеку javascript или python для запроса и получаете ответ, обычно в формате JSON {snacks: {cupcake,cookie,icecream}}, затем вы используете эту информацию, чтобы сделать что-то полезное, например отобразить ее на сайте или во внешнем интерфейсе приложения.
GraphQL - это просто еще один способ получить эту информацию (язык запросов), вам по-прежнему предоставляется конечная точка API, что-то вроде api.yummysnacks, но то, как вы запрашиваете информацию, отличается, вот как предыдущий запрос будет выглядеть как запрос graphQL:
query {
snacks{
type
}
}
В ответ вы получите следующее:
{
"data": {
"snacks": [
{
"type": "cupcake"
},
{
"type": "cookie"
},
{
"type": "ice cream"
}
]
}
}
Это может показаться странным и сложным синтаксисом, но главное преимущество состоит в том, что у вас есть принципиально другой (, но логичный) и значительно расширенный способ взаимодействия с данными (в определенных пределах, хотя ), позвольте мне объяснить ...
Когда вы запрашиваете через запрос REST API, вы не знаете, что получаете, с graphQL вы знаете; вы просили перекус type в запросе, в ответе вы получили именно тип закуски. Вы также можете запросить только ту информацию, которая вам нужна, допустим, мы хотели также запросить flavor, мы просто изменим наш запрос на:
query {
snacks{
type
flavor
}
}
И получите такой ответ:
{
"data": {
"snacks": [
{
"type": "cupcake",
"flavor": "blueberry"
},
{
"type": "cookie",
"flavor": "chocolate chip"
},
{
"type": "ice cream",
"flavor": "vanilla"
}
]
}
}
Для сравнения, REST api будет включать предопределенный набор атрибутов, и у вас нет другого выбора, кроме как получать их вместе с вашим запросом.
График говорите?
Возможно, самое сложное для понимания при переходе на GraphQL - это представление о том, что вы имеете дело с графом данных на другом конце ваших запросов, а не со статическими ответами, привязанными к конкретным запросам, здесь вы проходите по графу и получаете обратно объекты дерева ; тяжелые вещи.
Разновидность вашего сада Graph состоит из некоторых узлов и ребер, в graphQL ваши узлы представляют данные, а ребра - отношения между этими данными, наш запрос, например, будет выглядеть так:
И это дерево, которое мы извлекли из графа с помощью запроса.
Entry Points (or Root,Query types) If you look at both graphs, you might not see much of a similarity but that's because we need a place to start traversing the graph and that's what an entry point is :
Таким образом, мы могли бы запросить график для меню, закусок или напитков; эти типы корневых запросов предоставляются нам самим графом, о чем мы поговорим дальше.
Мы в основном закончили с теорией, ниже приведены более практические соображения из реального мира, хорошее место для перерыва, если он вам нужен.
Самоанализ и схемы
Схема графиков - это, по сути, карта, которую вы можете использовать для выполнения запросов, а интроспекция - это способ запросить график для указанной карты.
Допустим, вам предоставлена конечная точка api и больше ничего, ваша задача - создать интерфейсную панель управления, с чего начать?
BTW where do you get a practice graph ? https://github.com/APIs-guru/graphql-apis : Public graphQL endpoint collection. https://thegraph.com/explorer/ : Crypto related graphs with built-in playground.
Большинство конечных точек API-интерфейса graphQL приводят вас к интерфейсу graphiQL (или аналогичному), подобному этому:
https://graphql.org/swapi-graphql
On the left you type your query, hit play ▶ and get a result, on the right you can find your schema starting (Usually) from the root or root nodes. You can traverse the graph schema by clicking these elements or searching.
Мой любимый способ получить / понять схему - это графический обзор с использованием GraphQL Voyager и интроспекции. Самоанализ - это способ запросить схему у графа, и Voyager делает это очень просто:
- Go to the graphVoyager project demo and change the schema (1) - Copy the introspection query into your GraphiQl dashboard (2) - Copy/paste the response schema back into voyager (3) - Finally click Display (4) Notes: You can build your own Voyager Graph Explorer ! Just fork or include it into your project, consult the github. Sadly not all graphQL API's work ( use simple Introspection instead ), but those that do give you this:
You get a birds eye view of the graph you are querying, note the left zoomed Query which represents the entry points, if you compare that to our snacks graph it is fundamentally the same.
Вооружившись этими инструментами и ноу, как (и немного ручки и бумаги), вы можете планировать большинство своих запросов, давайте теперь рассмотрим некоторые конкретные реализации и запросы ...
Клиентские библиотеки
Итак, теперь вы знаете, как получить схему и имеете некоторое представление о том, как работает процесс запроса, теперь вам нужно начать работу над своим проектом, вам может потребоваться промежуточное программное обеспечение в виде клиента graphQL, которого есть много , попробуем парочку для Python и Javascript…
Python: gql
Install: pip install --pre gql
Example (HW_gql.py):
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport
sample_transport=RequestsHTTPTransport(
url='https://api.thegraph.com/subgraphs/name/graphprotocol/compound-v2',
verify=True,
retries=3,
)
client = Client(
transport=sample_transport
)
query = gql('''
query {
markets(first: 4) {
name
}
}
''')
response = client.execute(query)
print(response)
>>>
{'markets': [{'name': 'Compound Augur'}, {'name': 'Compound USD Coin'}, {'name': 'Compound Ether'}, {'name': 'Compound Dai'}]}
---------------------***---------------------
Give this script a graphQL api url, a query and you are set, if you need more options consult the documentation but it is pretty straightforward stuff.
Javascript vanilla:
const URL = 'https://api.thegraph.com/subgraphs/name/graphprotocol/compound-v2';
let content = {
"query": `{
markets(first: 4) {
name
}
}`
};
let body = JSON.stringify(content);
fetch(URL, {
method: 'post',
headers: {
'Content-Type': 'application/json'
},
body: body
})
.then(response => response.json())
.then(data => {
document.body.innerHTML = `<pre>${JSON.stringify(data, null, 2)}</pre>`;
});
Code source :https://css-tricks.com/raw-graphql-querying/
For simple requests and this introduction this should work, but if you are working with node or a front end framework check the list of clients (and do a search, new ones pop up all the time): graphql-clients
Основные запросы.
Теперь, когда у нас есть базовые реализации, настало время заняться некоторыми базовыми запросами, все эти запросы должны работать в выбранном вами клиенте, но поскольку каждый график немного отличается, вы должны использовать свою лапшу, чтобы адаптировать их к вашим потребностям ...
If for instance you want to get all the items from an entry point:
query allItems{
items{
id
itemData
}
}
Note that we are naming our query now (allItems), but beyond that it is the same query we saw at the start, we are also assuming that the schema has a root query called items and that each item has an id along with some itemData
Traversal
If you want to go one (or many) levels deeper you can traverse your graph like so:
query allItemsDataId{
items{
id
itemData{
id
}
}
}
Аргументы
Lets say you want a specific item and the graph allows you to retrieve it, usually through and id field; your query would look like this:
query specificThing{
item(id:"theThingsid"){
itemdata
}
}
Аргументы вызывают вопрос, откуда вы берете аргументы, если каждый график отличается? Несколько способов:
Here we are using the Uniswap graph... If you used the introspection query on voyager when you click on any root query you will get a field of arguments and their defaults, let's say you want the exchanges query arguments, those would be: (skip,first,orderBy,orderDirection,where,block) The arguments valid value can then be extracted if you open the exchanges field and select the argument, where in this case:
Итак, чтобы использовать where: Exchange_filter, мы должны выбрать значение, например, tokenSymbolto filter для определенного токена:
Graph source: https://thegraph.com/explorer/subgraph/graphprotocol/uniswap?query=Exchanges%20by%20volume query whereClause{ exchanges(where: {tokenSymbol:"WBTC"}) { id price priceUSD tokenName ethBalance tokenAddress tokenBalance ethLiquidity tokenLiquidity tokenSymbol tradeVolumeEth } } Run this query and you should get a specific exchange.
Вы также можете найти аргументы в своем интерфейсе GraphiQL при вводе запросов:
Что дальше:
В качестве практического введения я надеюсь, что это поможет вам начать работу, есть еще несколько тем и функций graphQL, на которые я бы указал вам, если вы хотите продолжить обучение, они также могут понадобиться для вашего проекта:
Мутации: которые позволяют изменять информацию на графике.
Переменные, фрагменты. Мы просто отказались от информации, которую вы можете использовать для составления запросов, переменных и фрагментов справки по сложным запросам.
Аутентификация. Некоторые графики требуют, чтобы вы прошли аутентификацию для запроса и выполнения мутаций.
Более глубокое понимание типов и схем.
Подписки: получайте уведомления при изменении графика.
Подайте график
Интеграция с фреймворком
Для получения дополнительной информации по вышеизложенному я бы направил вас по следующим ссылкам:
Спасибо за чтение !
