From ba8ccc32f0301efad8c48800749fc1175bbe882f Mon Sep 17 00:00:00 2001 From: Joe Perez Date: Mon, 22 Jul 2024 13:58:52 -0700 Subject: [PATCH 1/2] Split 'fetch frontend' topic into two --- .../fetch-data-from-frontend-app-plugins.md | 119 ++++++++++++++++++ ...data-from-frontend-data-source-plugins.md} | 53 ++------ docusaurus/website/docusaurus.config.base.js | 2 +- 3 files changed, 131 insertions(+), 43 deletions(-) create mode 100644 docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md rename docusaurus/docs/how-to-guides/data-source-plugins/{fetch-data-from-frontend.md => fetch-data-from-frontend-data-source-plugins.md} (84%) diff --git a/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md b/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md new file mode 100644 index 000000000..e68c6c0d3 --- /dev/null +++ b/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md @@ -0,0 +1,119 @@ +--- +id: fetch-data-from-frontend-app-plugins +title: Fetch data from frontend code using the data proxy +description: Learn how to use the data proxy API to fetch data from a frontend app plugin +keywords: + - grafana + - plugins + - data proxy + - frontend + - data source + - CORS + - app + - app plugin +--- + +# Fetch data from frontend app plugins + +Along with the JavaScript [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), the Grafana data proxy is used to fetch data from a Grafana app plugin (or [a data source plugin](../data-source-plugins/fetch-data-from-frontend-data-source-plugins)). + +The data proxy is especially useful + +- for overcoming cross-site (CORS) limitations, or +- for performing authenticated requests, or +- for sending other sensitive data from your plugin configuration to Grafana. + +This guide explains how the data proxy works in general and explores common issues in its usage in frontend app plugins. + +## How does it work? + +Instead of performing a request directly from the browser to the server, you perform the request through the Grafana backend server, which handles it and returns the response to the plugin. + +- **Without data proxy**: The requests go directly from the browser to the third-party server. +- **With data proxy**: The requests go from the browser to the Grafana backend and then to the third-party server. In this case, there are no restrictions in CORS, and you can instruct Grafana to send the request authenticated by using sensitive data stored in the plugin configuration. + +:::note + +You can only make use of the data proxy from app plugins and data source plugins. _You can't use the data proxy from panel plugins._ + +::: + + +## Use the data proxy within an app plugin + +The setup of routes in your `plugin.json` metadata remains the same as in a data source plugin. However, since app plugins don't receive the URL as part of the props, the URL is constructed like this: + +```typescript +const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/yourRoutePath`; +``` + +Here is an example of a function that fetches data from the data proxy in an app plugin: + +1. Declare the route in `src/plugin.json`. You may also use authenticated requests and `jsonData` interpolation like in data source plugins. + + ```json title="src/plugin.json" + "routes": [ + { + "path": "myRoutePath", + "url": "https://api.example.com", + // jsonData interpolation is also possible + //"url": "{{ .JsonData.apiUrl }}", + }] + ``` + +1. In your app plugin's code, you can then fetch data using the data proxy by constructing the data proxy URL like this: + + ```typescript title="src/dataproxy-api-example.ts" + import { getBackendSrv } from '@grafana/runtime'; + import { lastValueFrom } from 'rxjs'; + + async function getDataFromApi() { + const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/myRoutePath`; + const response = getBackendSrv().fetch({ + url: dataProxyUrl, + }); + return await lastValueFrom(response); + } + ``` + +## Use other HTTP methods (for example, POST, PUT, DELETE) with the data proxy + +You can specify the method directly in the `fetch` method. Your routes in `src/plugin.json` remain the same: + +```typescript +const response = getBackendSrv().fetch({ + url: `${this.baseUrl}`, + method: 'POST', + data: dataToSendViaPost, +}); +``` + +## Add authentication to your requests using the data proxy + +To learn about adding authentication to the data proxy, refer to our [documentation](https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-annotations-for-data-source-plugins) (./add-annotations-for-data-source-plugins). + +## Debug requests from the data proxy + +If you want to debug the requests that are going from the Grafana backend to your API, enable the data proxy logging in the [configuration](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#dataproxy). + +You must also [enable debug logs](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#mode) in Grafana to be able to see the data proxy logs in your Grafana configuration file. + +**Example:** + +``` +[log] +level = debug + +[dataproxy] +logging = true +``` + +With this configuration, the Grafana server output shows the requests going out to your API from the data proxy. + +## Send special headers using the data proxy + +You can send special headers using the data proxy. To learn about adding headers to the data proxy, refer to our [documentation](./add-authentication-for-data-source-plugins). + +## See also + +Learn how to fetch data from [frontend data source plugins](../data-source-plugins/fetch-data-from-frontend-data-source-plugins). diff --git a/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend.md b/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md similarity index 84% rename from docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend.md rename to docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md index c98cc3bfa..95702d6e5 100644 --- a/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend.md +++ b/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md @@ -1,7 +1,7 @@ --- -id: fetch-data-from-frontend +id: fetch-data-from-frontend-data-source-plugins title: Fetch data from frontend code using the data proxy -description: Learn how to use the data proxy API to fetch data from frontend code in data source and app plugins in Grafana +description: Learn how to use the data proxy API to fetch data from frontend code in data source plugins. keywords: - grafana - plugins @@ -11,9 +11,9 @@ keywords: - CORS --- -# Fetch data from frontend data source and app plugins +# Fetch data from frontend data source plugins -Along with the JavaScript [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), the Grafana data proxy is used to fetch data from a Grafana data source plugin or app plugin. +Along with the JavaScript [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), the Grafana data proxy is used to fetch data from a Grafana data source plugin (and [an app plugin](../app-plugins/fetch-data-from-frontend-app-plugins)). The data proxy is especially useful @@ -21,7 +21,7 @@ The data proxy is especially useful - for performing authenticated requests, or - for sending other sensitive data from your plugin configuration to Grafana. -This guide explains how the data proxy works and explores common issues in its usage. +This guide explains how the data proxy works and explores common issues in its usage in data source plugins. ## How does it work? @@ -31,7 +31,9 @@ Instead of performing a request directly from the browser to the server, you per - **With data proxy**: The requests go from the browser to the Grafana backend and then to the third-party server. In this case, there are no restrictions in CORS, and you can instruct Grafana to send the request authenticated by using sensitive data stored in the plugin configuration. :::note + You can only make use of the data proxy from data source and app plugins. _You can't use the data proxy from panel plugins._ + ::: ## How to use the data proxy in data source plugins @@ -198,43 +200,6 @@ In your data source plugin, you can now fetch data by using the proxy URL. Refer to the [previous example](#step-2-create-your-configuration-page), as the code is the same. -## Use the data proxy within an app plugin - -The setup of routes in your `plugin.json` metadata remains the same as in a data source plugin. However, since app plugins don't receive the URL as part of the props, the URL is constructed like this: - -```typescript -const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/yourRoutePath`; -``` - -Here is an example of a function that fetches data from the data proxy in an app plugin: - -Declare the route in `src/plugin.json`. You may also use authenticated requests and `jsonData` interpolation like in data source plugins. - -```json title="src/plugin.json" -"routes": [ -{ - "path": "myRoutePath", - "url": "https://api.example.com", - // jsonData interpolation is also possible - //"url": "{{ .JsonData.apiUrl }}", -}] -``` - -In your app plugin's code, you can then fetch data using the data proxy by constructing the data proxy URL like this: - -```typescript title="src/dataproxy-api-example.ts" -import { getBackendSrv } from '@grafana/runtime'; -import { lastValueFrom } from 'rxjs'; - -async function getDataFromApi() { - const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/myRoutePath`; - const response = getBackendSrv().fetch({ - url: dataProxyUrl, - }); - return await lastValueFrom(response); -} -``` - ## Use other HTTP methods (for example, POST, PUT, DELETE) with the data proxy You can specify the method directly in the `fetch` method. Your routes in `src/plugin.json` remain the same: @@ -272,3 +237,7 @@ With this configuration, the Grafana server output shows the requests going out ## Send special headers using the data proxy You can send special headers using the data proxy. To learn about adding headers to the data proxy, refer to our [documentation](./add-authentication-for-data-source-plugins). + +## See also + +Learn how to fetch data from [frontend app plugins](../app-plugins/fetch-data-from-frontend-app-plugins). diff --git a/docusaurus/website/docusaurus.config.base.js b/docusaurus/website/docusaurus.config.base.js index b74418d4b..0453d0e89 100644 --- a/docusaurus/website/docusaurus.config.base.js +++ b/docusaurus/website/docusaurus.config.base.js @@ -159,7 +159,7 @@ const plugins = [ }, { from: ['/create-a-plugin/extend-a-plugin/fetch-data-from-frontend'], - to: '/how-to-guides/data-source-plugins/fetch-data-from-frontend', + to: '/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins', }, { from: ['/create-a-plugin/extend-a-plugin/include-dashboards'], From f19f1da2858d186bc450a7f3f21018dd4864fe15 Mon Sep 17 00:00:00 2001 From: Joe Perez Date: Mon, 22 Jul 2024 14:05:48 -0700 Subject: [PATCH 2/2] Minor fix --- .../fetch-data-from-frontend-app-plugins.md | 45 +++++++++---------- ...-data-from-frontend-data-source-plugins.md | 4 +- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md b/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md index e68c6c0d3..9475e780e 100644 --- a/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md +++ b/docusaurus/docs/how-to-guides/app-plugins/fetch-data-from-frontend-app-plugins.md @@ -1,6 +1,6 @@ --- id: fetch-data-from-frontend-app-plugins -title: Fetch data from frontend code using the data proxy +title: Fetch data from frontend app plugin using the data proxy description: Learn how to use the data proxy API to fetch data from a frontend app plugin keywords: - grafana @@ -38,7 +38,6 @@ You can only make use of the data proxy from app plugins and data source plugins ::: - ## Use the data proxy within an app plugin The setup of routes in your `plugin.json` metadata remains the same as in a data source plugin. However, since app plugins don't receive the URL as part of the props, the URL is constructed like this: @@ -51,30 +50,30 @@ Here is an example of a function that fetches data from the data proxy in an app 1. Declare the route in `src/plugin.json`. You may also use authenticated requests and `jsonData` interpolation like in data source plugins. - ```json title="src/plugin.json" - "routes": [ - { - "path": "myRoutePath", - "url": "https://api.example.com", - // jsonData interpolation is also possible - //"url": "{{ .JsonData.apiUrl }}", - }] - ``` + ```json title="src/plugin.json" + "routes": [ + { + "path": "myRoutePath", + "url": "https://api.example.com", + // jsonData interpolation is also possible + //"url": "{{ .JsonData.apiUrl }}", + }] + ``` 1. In your app plugin's code, you can then fetch data using the data proxy by constructing the data proxy URL like this: - ```typescript title="src/dataproxy-api-example.ts" - import { getBackendSrv } from '@grafana/runtime'; - import { lastValueFrom } from 'rxjs'; - - async function getDataFromApi() { - const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/myRoutePath`; - const response = getBackendSrv().fetch({ - url: dataProxyUrl, - }); - return await lastValueFrom(response); - } - ``` + ```typescript title="src/dataproxy-api-example.ts" + import { getBackendSrv } from '@grafana/runtime'; + import { lastValueFrom } from 'rxjs'; + + async function getDataFromApi() { + const dataProxyUrl = `api/plugin-proxy/${PLUGIN_ID}/myRoutePath`; + const response = getBackendSrv().fetch({ + url: dataProxyUrl, + }); + return await lastValueFrom(response); + } + ``` ## Use other HTTP methods (for example, POST, PUT, DELETE) with the data proxy diff --git a/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md b/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md index 95702d6e5..a145713d9 100644 --- a/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md +++ b/docusaurus/docs/how-to-guides/data-source-plugins/fetch-data-from-frontend-data-source-plugins.md @@ -1,6 +1,6 @@ --- id: fetch-data-from-frontend-data-source-plugins -title: Fetch data from frontend code using the data proxy +title: Fetch data from frontend data source plugin using the data proxy description: Learn how to use the data proxy API to fetch data from frontend code in data source plugins. keywords: - grafana @@ -214,7 +214,7 @@ const response = getBackendSrv().fetch({ ## Add authentication to your requests using the data proxy -To learn about adding authentication to the data proxy, refer to our [documentation](https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-annotations-for-data-source-plugins) (./add-annotations-for-data-source-plugins). +To learn about adding authentication to the data proxy, refer to our [documentation](https://grafana.com/developers/plugin-tools/how-to-guides/data-source-plugins/add-annotations-for-data-source-plugins). ## Debug requests from the data proxy