From f298bb16d8125180acc0723a003e44d9c85cc4f0 Mon Sep 17 00:00:00 2001 From: josefaidt Date: Tue, 17 Dec 2024 10:51:50 -0800 Subject: [PATCH 1/3] add page for configuring client library in functions --- cspell.json | 3 +- src/directory/directory.mjs | 3 + .../configure-client-library/index.mdx | 94 +++++++++++++++++++ 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx diff --git a/cspell.json b/cspell.json index 49baa6ee1e1..58d78fcbfd3 100644 --- a/cspell.json +++ b/cspell.json @@ -1618,7 +1618,8 @@ "knowledgebases", "rehype", "assetlinks", - "AMPLIFYRULES" + "AMPLIFYRULES", + "preconfigured" ], "flagWords": ["hte", "full-stack", "Full-stack", "Full-Stack", "sudo"], "patterns": [ diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index 269af6f34ad..509cab649cf 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -396,6 +396,9 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/functions/configure-functions/index.mdx' }, + { + path: 'src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx' + }, { path: 'src/pages/[platform]/build-a-backend/functions/scheduling-functions/index.mdx' }, diff --git a/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx b/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx new file mode 100644 index 00000000000..643cac84294 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx @@ -0,0 +1,94 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Configure client library', + description: + 'Learn how to configure the aws-amplify client library in function handlers', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export function getStaticPaths() { + return getCustomStaticPath(meta.platforms); +} + +export function getStaticProps() { + return { + props: { + meta + } + }; +} + +The [`aws-amplify`](https://www.npmjs.com/package/aws-amplify) client library can be configured for use inside function handler files by using the credentials available from the AWS Lambda runtime. To get started, use the `getAmplifyDataClientConfig` from the backend runtime package and pass the generated `env` object to retrieve the preconfigured `resourceConfig` and `libraryOptions`. + +```ts title="amplify/my-function/handler.ts" +import { getAmplifyDataClientConfig } from '@aws-amplify/backend/function/runtime'; +import { env } from '$amplify/env/my-function'; + +const { resourceConfig, libraryOptions } = await getAmplifyDataClientConfig( + env +); +``` + + + +When configuring Amplify with `getAmplifyDataClientConfig`, your function consumes schema information from an Amazon S3 bucket created during backend deployment with grants for the access your function need to use it. Any changes to this bucket outside of backend deployment may break your function. + + + +`resourceConfig` and `libraryOptions` are returned for you to pass into `Amplify.configure`. This will instruct the client library which resources it can interact with, and where to retrieve AWS credentials to use when signing requests to those resources. + +```ts title="amplify/my-function/handler.ts" +import { getAmplifyDataClientConfig } from '@aws-amplify/backend/function/runtime'; +// highlight-next-line +import { Amplify } from 'aws-amplify'; +import { env } from '$amplify/env/my-function'; + +const { resourceConfig, libraryOptions } = await getAmplifyDataClientConfig( + env +); + +// highlight-next-line +Amplify.configure(resourceConfig, libraryOptions); +``` + +The client library will now have access to perform operations against other AWS resources as specified by the function's IAM role. This is handled for you when [granting access to other resources using the `access` property](/[platform]/build-a-backend/functions/grant-access-to-other-resources/#using-the-access-property), however it can also be [extended using CDK](/[platform]/build-a-backend/functions/grant-access-to-other-resources/#using-cdk). + +## Under the hood + +The `getAmplifyDataClientConfig` function assists with creating the arguments' values to pass to `Amplify.configure`, which reads from the generated `env` object in order to produce configuration for the resources you have granted your function access to interact with. Under the hood this is also generating the configuration that specifies how the client library should behave, namely where the library should read credentials. + +```ts title="amplify/my-function/handler.ts" +import { env } from "$amplify/env/my-function"; + +Amplify.configure( + {/* resource configuration */}, + { + Auth: { + credentialsProvider: { + // instruct the client library to read credentials from the environment + getCredentialsAndIdentityId: async () => ({ + credentials: { + accessKeyId: env.AWS_ACCESS_KEY_ID, + secretAccessKey: env.AWS_SECRET_ACCESS_KEY, + sessionToken: env.AWS_SESSION_TOKEN, + }, + }), + clearCredentialsAndIdentityId: () => { + /* noop */ + }, + }, + }, + } +); +``` From e5542eaea33feadeebed21448d81dc4bfb1878a0 Mon Sep 17 00:00:00 2001 From: josef Date: Fri, 31 Jan 2025 16:14:19 -0800 Subject: [PATCH 2/3] Update src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx Co-authored-by: Kethan sai --- .../functions/configure-client-library/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx b/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx index 643cac84294..08ee7cf50d5 100644 --- a/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx +++ b/src/pages/[platform]/build-a-backend/functions/configure-client-library/index.mdx @@ -42,7 +42,7 @@ const { resourceConfig, libraryOptions } = await getAmplifyDataClientConfig( -When configuring Amplify with `getAmplifyDataClientConfig`, your function consumes schema information from an Amazon S3 bucket created during backend deployment with grants for the access your function need to use it. Any changes to this bucket outside of backend deployment may break your function. +When using `getAmplifyDataClientConfig`, your function requires schema information stored in an Amplify deployed Amazon S3 bucket. This bucket is created during backend deployment and includes necessary access grants for your function. Modifying this bucket outside of the backend deployment process may cause unexpected failures on your function. From 5ef550aabbf579bf5d4122ace23a3e0a7cbf6f04 Mon Sep 17 00:00:00 2001 From: ashika112 <155593080+ashika112@users.noreply.github.com> Date: Fri, 18 Apr 2025 15:25:08 -0700 Subject: [PATCH 3/3] Update cspell.json --- cspell.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cspell.json b/cspell.json index 2cb581d162b..df50ce23af3 100644 --- a/cspell.json +++ b/cspell.json @@ -1623,7 +1623,7 @@ "rehype", "assetlinks", "AMPLIFYRULES", - "preconfigured" + "preconfigured", "manylinux", "GOARCH", "norpc"