mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-25 00:13:11 +03:00
9c27f66768
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/2540 Co-authored-by: Tirumarai Selvan <8663570+tirumaraiselvan@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: d9318aca67646c29b5d951a5d0603fc463e1467b
282 lines
7.0 KiB
ReStructuredText
282 lines
7.0 KiB
ReStructuredText
.. meta::
|
|
:description: Transform actions requests
|
|
:keywords: hasura, docs, action, transform
|
|
|
|
.. _action_transforms:
|
|
|
|
Actions transforms
|
|
==================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 2
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Transforms are used to perform transformations on the HTTP
|
|
request generated by an action.
|
|
|
|
.. admonition:: Supported from
|
|
|
|
Transforms are supported in Hasura GraphQL Engine versions ``v2.1.0`` and above
|
|
|
|
Configuring actions transforms
|
|
------------------------------
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Console
|
|
|
|
Go to the ``Actions`` tab on the console and create or modify an action. Scroll down to ``Configure Transformations`` section:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/configure-transformation.png
|
|
:alt: Configure action transformation
|
|
:width: 70%
|
|
|
|
|
|
.. tab:: API
|
|
|
|
Action transforms can be added to actions using the :ref:`create_action metadata API <metadata_create_action>` or
|
|
:ref:`update_action metadata API <metadata_update_action>` by adding a
|
|
:ref:`request_transform <RequestTransformation>` field to the args:
|
|
|
|
|
|
.. code-block:: http
|
|
:emphasize-lines: 24-26
|
|
|
|
POST /v1/metadata HTTP/1.1
|
|
Content-Type: application/json
|
|
X-Hasura-Role: admin
|
|
|
|
{
|
|
"type":"create_action",
|
|
"args":{
|
|
"name":"create_user",
|
|
"definition":{
|
|
"kind":"synchronous",
|
|
"arguments":[
|
|
{
|
|
"name":"username",
|
|
"type":"String!"
|
|
},
|
|
{
|
|
"name":"email",
|
|
"type":"String!"
|
|
}
|
|
],
|
|
"output_type":"User",
|
|
"handler":"https://action.my_app.com/create-user",
|
|
"timeout":60,
|
|
"request_transform": {
|
|
"body": "{{$body.input.name}}"
|
|
},
|
|
},
|
|
"comment": "Custom action to create user"
|
|
}
|
|
}
|
|
|
|
Types of transformations
|
|
------------------------
|
|
|
|
You can practically create an arbitrary request using the context available in the Action execution.
|
|
The context variables available during transformation are:
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Context variable
|
|
- Value
|
|
* - $body
|
|
- Original body of action request
|
|
* - $base_url
|
|
- Original configured URL
|
|
* - $session_variables
|
|
- Session variables
|
|
|
|
Request body
|
|
************
|
|
|
|
Generate a custom body by giving a ``body`` key to the ``request_transform``.
|
|
You can use the `Kriti templating language <https://github.com/hasura/kriti-lang>`__ to construct the body.
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
|
|
.. tab:: Console
|
|
|
|
In the ``Configure Transformations`` section, click on ``Add Payload Transformation``:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/payload-transformation.png
|
|
:alt: Add payload transformation
|
|
:width: 90%
|
|
|
|
|
|
.. tab:: API
|
|
|
|
.. code-block:: json
|
|
:emphasize-lines: 3-6
|
|
|
|
{
|
|
"request_transform": {
|
|
"body": {
|
|
"name": "{{$body.input.name}}",
|
|
"email": "{{$body.input.email}}"
|
|
}
|
|
}
|
|
}
|
|
|
|
Content Type
|
|
************
|
|
|
|
You can change the ``Content-Type`` of the request to either ``application/json`` or ``x-www-form-urlencoded``. The default is ``application/json``.
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Console
|
|
|
|
Console support coming soon.
|
|
|
|
.. tab:: API
|
|
|
|
.. code-block:: json
|
|
:emphasize-lines: 7
|
|
|
|
{
|
|
"request_transform": {
|
|
"body": {
|
|
"name": "{{$body.input.name}}",
|
|
"email": "{{$body.input.email}}",
|
|
},
|
|
"content_type": "x-www-form-urlencoded"
|
|
}
|
|
}
|
|
|
|
With ``x-www-form-urlencoded``, the key-value pairs in ``body`` are transformed to ``name={{$body.input.name}}&key2={{$body.input.email}}``.
|
|
|
|
URL
|
|
***
|
|
|
|
Transform the request URL. This can be used to embed, say user-id, in the url path.
|
|
You can also provide ``query_params`` to add to the URL.
|
|
You can use the `Kriti templating language <https://github.com/hasura/kriti-lang>`__ to construct any string value here.
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
.. tab:: Console
|
|
|
|
In the ``Configure Transformations`` section, click on ``Add Request Options Transformation``:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/request-options-transformation.png
|
|
:alt: Console action create
|
|
:width: 90%
|
|
|
|
.. tab:: API
|
|
|
|
.. code-block:: json
|
|
:emphasize-lines: 3
|
|
|
|
{
|
|
"request_transform": {
|
|
"url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
|
|
"query_params": {
|
|
"param1": "{{$body.input.value1}}",
|
|
"param2": "{{$body.input.value2}}"
|
|
}
|
|
}
|
|
}
|
|
|
|
.. admonition:: escapeUri
|
|
|
|
Note that you must use the ``escapeUri`` function to urlencode templated values.
|
|
For example, if you have to use session variables in the URL and those may contain non-ASCII values,
|
|
then you should provide the template URL as ``{{$base_url}}/{{escapeUri $session_variables['x-hasura-user-id']}}``
|
|
|
|
Method
|
|
******
|
|
|
|
Transform the method. This can be used to change the request method, say from ``POST`` to ``GET``, as shown below.
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Console
|
|
|
|
In the ``Configure Transformations`` section, click on ``Add Request Options Transformation``:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/request-options-transformation.png
|
|
:alt: Console action create
|
|
:width: 90%
|
|
|
|
.. tab:: API
|
|
|
|
.. code-block:: json
|
|
:emphasize-lines: 3
|
|
|
|
{
|
|
"request_transform": {
|
|
"method": "GET",
|
|
"url": "$base_url/{{$session_variables['x-hasura-user-id']}}"
|
|
}
|
|
}
|
|
|
|
Example
|
|
-------
|
|
|
|
Let's integrate Auth0's management API to update the profile of a user:
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
|
|
.. tab:: Console
|
|
|
|
Go to the ``Actions`` tab on the console and create or modify an action. Scroll down to ``Configure Transformations`` section:
|
|
|
|
Action definition:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/example-transformation-0.png
|
|
:alt: Console action create
|
|
:width: 90%
|
|
|
|
The transformation is given by:
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/example-transformation-1.png
|
|
:alt: Console action create
|
|
:width: 90%
|
|
|
|
.. thumbnail:: /img/graphql/core/actions/example-transformation-2.png
|
|
:alt: Console action create
|
|
:width: 90%
|
|
|
|
.. tab:: API
|
|
|
|
Action definition:
|
|
|
|
.. code-block:: graphql
|
|
|
|
type Mutation {
|
|
updateProfile(picture_url : String!) : ProfileOutput
|
|
}
|
|
|
|
type ProfileOutput {
|
|
id: String!
|
|
user_metadata: String!
|
|
}
|
|
|
|
The transform is given by:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"request_transform": {
|
|
"body": "{\"user_metadata\": {\"picture\": {{$body.input.picture_url}} } }",
|
|
"url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
|
|
"method": "PATCH"
|
|
}
|
|
}
|