1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
.. _appsync_transport:
AppSyncWebsocketsTransport
==========================
AWS AppSync allows you to execute GraphQL subscriptions on its realtime GraphQL endpoint.
See `Building a real-time websocket client`_ for an explanation.
GQL provides the :code:`AppSyncWebsocketsTransport` transport which implements this
for you to allow you to execute subscriptions.
.. note::
It is only possible to execute subscriptions with this transport.
For queries or mutations, See :ref:`AppSync GraphQL Queries and mutations <appsync_http>`
How to use it:
* choose one :ref:`authentication method <appsync_authentication_methods>` (API key, IAM, Cognito user pools or OIDC)
* instantiate a :code:`AppSyncWebsocketsTransport` with your GraphQL endpoint as url and your auth method
.. note::
It is also possible to instantiate the transport without an auth argument. In that case,
gql will use by default the :class:`IAM auth <gql.transport.appsync_auth.AppSyncIAMAuthentication>`
which will try to authenticate with environment variables or from your aws credentials file.
.. note::
All the examples in this documentation are based on the sample app created
by following `this AWS blog post`_
Full example with API key authentication from environment variables:
.. literalinclude:: ../code_examples/appsync/subscription_api_key.py
Reference: :class:`gql.transport.appsync_websockets.AppSyncWebsocketsTransport`
.. _Building a real-time websocket client: https://docs.aws.amazon.com/appsync/latest/devguide/real-time-websocket-client.html
.. _this AWS blog post: https://aws.amazon.com/fr/blogs/mobile/appsync-realtime/
.. _appsync_authentication_methods:
Authentication methods
----------------------
.. _appsync_api_key_auth:
API key
^^^^^^^
Use the :code:`AppSyncApiKeyAuthentication` class to provide your API key:
.. code-block:: python
auth = AppSyncApiKeyAuthentication(
host="XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com",
api_key="YOUR_API_KEY",
)
transport = AppSyncWebsocketsTransport(
url="https://XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com/graphql",
auth=auth,
)
Reference: :class:`gql.transport.appsync_auth.AppSyncApiKeyAuthentication`
.. _appsync_iam_auth:
IAM
^^^
For the IAM authentication, you can simply create your transport without
an auth argument.
The region name will be autodetected from the url or from your AWS configuration
(:code:`.aws/config`) or the environment variable:
- AWS_DEFAULT_REGION
The credentials will be detected from your AWS configuration file
(:code:`.aws/credentials`) or from the environment variables:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN (optional)
.. code-block:: python
transport = AppSyncWebsocketsTransport(
url="https://XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com/graphql",
)
OR You can also provide the credentials manually by creating the
:code:`AppSyncIAMAuthentication` class yourself:
.. code-block:: python
from botocore.credentials import Credentials
credentials = Credentials(
access_key = os.environ.get("AWS_ACCESS_KEY_ID"),
secret_key= os.environ.get("AWS_SECRET_ACCESS_KEY"),
token=os.environ.get("AWS_SESSION_TOKEN", None), # Optional
)
auth = AppSyncIAMAuthentication(
host="XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com",
credentials=credentials,
region_name="your region"
)
transport = AppSyncWebsocketsTransport(
url="https://XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com/graphql",
auth=auth,
)
Reference: :class:`gql.transport.appsync_auth.AppSyncIAMAuthentication`
.. _appsync_jwt_auth:
Json Web Tokens (jwt)
^^^^^^^^^^^^^^^^^^^^^
AWS provides json web tokens (jwt) for the authentication methods:
- Amazon Cognito user pools
- OpenID Connect (OIDC)
For these authentication methods, you can use the :code:`AppSyncJWTAuthentication` class:
.. code-block:: python
auth = AppSyncJWTAuthentication(
host="XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com",
jwt="YOUR_JWT_STRING",
)
transport = AppSyncWebsocketsTransport(
url="https://XXXXXXXXXXXXXXXXXXXXXXXXXX.appsync-api.REGION.amazonaws.com/graphql",
auth=auth,
)
Reference: :class:`gql.transport.appsync_auth.AppSyncJWTAuthentication`
.. _appsync_http:
AppSync GraphQL Queries and mutations
-------------------------------------
Queries and mutations are not allowed on the realtime websockets endpoint.
But you can use the :ref:`AIOHTTPTransport <aiohttp_transport>` to create
a normal http session and reuse the authentication classes to create the headers for you.
Full example with API key authentication from environment variables:
.. literalinclude:: ../code_examples/appsync/mutation_api_key.py
From the command line
---------------------
Using :ref:`gql-cli <gql_cli>`, it is possible to execute GraphQL queries and subscriptions
from the command line on an AppSync endpoint.
- For queries and mutations, use the :code:`--transport appsync_http` argument::
# Put the request in a file
$ echo 'mutation createMessage($message: String!) {
createMessage(input: {message: $message}) {
id
message
createdAt
}
}' > mutation.graphql
# Execute the request using gql-cli with --transport appsync_http
$ cat mutation.graphql | gql-cli $AWS_GRAPHQL_API_ENDPOINT --transport appsync_http -V message:"Hello world!"
- For subscriptions, use the :code:`--transport appsync_websockets` argument::
echo "subscription{onCreateMessage{message}}" | gql-cli $AWS_GRAPHQL_API_ENDPOINT --transport appsync_websockets
- You can also get the full GraphQL schema from the backend from introspection::
$ gql-cli $AWS_GRAPHQL_API_ENDPOINT --transport appsync_http --print-schema > schema.graphql
|
