Chamar APIs do AEM baseadas em OpenAPI usando a autenticação do OAuth Web App

Saiba como chamar APIs do AEM baseadas em OpenAPI no AEM as a Cloud Service usando a autenticação baseada em usuário de um aplicativo Web personalizado que usa o OAuth Web App.

A autenticação do Aplicativo Web OAuth é ideal para aplicativos Web com componentes de front-end e back-end que precisam acessar APIs do AEM em nome de um usuário. Ele usa o tipo de concessão OAuth 2.0 authorization_code para obter um token de acesso em nome do usuário para acessar as APIs do AEM. Para obter mais informações, consulte Diferença entre credenciais de servidor para servidor do OAuth vs. aplicativo da Web vs. aplicativo de página única.

O que você aprenderá what-you-learn

Neste tutorial, você aprenderá a:

Antes de começar, verifique se você revisou o seguinte:

Aplicativo Web de amostra: Visão geral e fluxo funcional do WKND-PIM

Vamos entender o aplicativo da Web de amostra, o Gerenciamento de informações de produto (PIM) da WKND e seu fluxo funcional.

O aplicativo WKND PIM é um aplicativo da Web de amostra projetado para gerenciar atributos de produto e seus metadados de ativos armazenados no AEM as a Cloud Service. Este exemplo demonstra como os aplicativos da Web podem se integrar perfeitamente às APIs do Adobe para fornecer fluxos de trabalho eficientes e centrados no usuário.

O projeto Adobe Developer Console (ADC) é configurado para acessar a API do autor do Assets usando a autenticação do aplicativo web OAuth. Ele fornece o client_id e o client_secret necessários ao aplicativo Web WKND-PIM para iniciar o fluxo de concessão do authorization_code.

O diagrama a seguir ilustra o fluxo funcional do aplicativo Web WKND-PIM obtendo tokens de acesso específicos do usuário para interagir com a API do Assets Author.

O aplicativo Web WKND-PIM é desenvolvido com o Node.js e o Express. O Express atua como o servidor que gerencia com segurança segredos privados e tokens de acesso específicos do usuário.

Outras pilhas da Web (Java, Python, baseado em .NET etc.) podem ser usadas para criar aplicativos Web que se integram às APIs do Adobe usando as abordagens ilustradas neste tutorial.

Como usar este tutorial how-to-use-this-tutorial

Você pode Revisar a seção de trechos de código da chave do aplicativo Web para entender o fluxo de autenticação do aplicativo Web OAuth e os trechos de código de chamadas da API usados no aplicativo Web WKND-PIM. Ou prossiga diretamente para a seção Configurar e executar o aplicativo Web para configurar e executar o aplicativo Web WKND-PIM no computador local para entender o fluxo de autenticação e as chamadas de API do aplicativo Web OAuth.

Revisar trechos de código-chave do aplicativo da Web review-web-app-key-code-snippets

Vamos analisar os trechos de código principais usados no aplicativo Web WKND-PIM para entender o fluxo de autenticação do aplicativo Web OAuth e as chamadas de API.

Baixe o código do aplicativo Web WKND-PIM

Autenticação de usuário IMS e autorização de aplicativo

Vamos revisar o código que inicia a autenticação de usuário IMS e a autorização do aplicativo. Para revisar ou atualizar os metadados do ativo, o usuário deve se autenticar no Adobe IMS e autorizar que o aplicativo Web WKND-PIM acesse a API do autor do Assets em nome dele.

Na primeira tentativa de logon, o usuário deve fornecer consentimento para permitir que o aplicativo Web WKND-PIM acesse a API do autor do Assets em nome dele.

Se o usuário não estiver autenticado no Adobe IMS, a página de logon do Adobe ID será exibida solicitando a autenticação do usuário.

Se já estiver autenticado, o usuário será redirecionado de volta para o redirect_uri especificado do aplicativo Web WKND-PIM com um authorization_code.

Recuperação de token de acesso

O aplicativo Web WKND-PIM troca com segurança o authorization_code com o Adobe IMS por um token de acesso específico do usuário usando o client_id e o client_secret da credencial do aplicativo Web OAuth do projeto ADC.

No arquivo routes/adobe-ims-auth.js, a rota /callback troca o authorization_code com o Adobe IMS para um token de acesso específico do usuário.

...
// Callback route to exchange authorization code for access token
router.get("/callback", async (req, res) => {
  // Extracting authorization code from the query parameters
  const authorizationCode = req.query.code;

  if (!authorizationCode) {
    return res.status(400).send("Missing authorization code");
  }

  // Exchange authorization code for access token
  try {
    // Fetch access token from Adobe IMS token endpoint
    const response = await fetch(adobeIMSConfig.tokenEndpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        Authorization: `Basic ${Buffer.from(
          `${adobeADCConfig.clientId}:${adobeADCConfig.clientSecret}`
        ).toString("base64")}`,
      },
      body: new URLSearchParams({
        code: authorizationCode,
        grant_type: "authorization_code",
      }),
    });

    if (!response.ok) {
      console.error("Failed to fetch access token:", response.statusText);
      return res.status(500).send("Failed to fetch access token");
    }

    const data = await response.json();

    if (!data.access_token) {
      console.error("Access token missing in the response:", data);
      return res.status(500).send("Invalid response from token endpoint");
    }

    // For debugging purposes
    console.log("Access token:", data.access_token);

    // Store the access token in the session
    req.session.accessToken = data.access_token;

    // Redirect user to update product attributes
    res.redirect("/update-product-attributes");
  } catch (error) {
    console.error("Error exchanging authorization code:", error);
    res.status(500).send("Error during token exchange");
  }
});

O token de acesso é armazenado na sessão expressa para solicitações subsequentes à API do autor do Assets.

Acesso a APIs do AEM baseadas em OpenAPI usando o token de acesso

O aplicativo Web WKND-PIM usa com segurança o token de acesso específico do usuário para interagir com a API do autor do Assets, permitindo que o usuário recupere ou atualize os metadados de ativos do produto.

No arquivo routes/invoke-aem-apis.js, as rotas /api/getAEMAssetMetadata e /api/updateAEMAssetMetadata invocam as APIs de Autor do Assets usando o token de acesso.

...
// API Route: Get AEM Asset Metadata
router.get("/api/getAEMAssetMetadata", async (req, res) => {
  const assetId = req.query.assetId;
  const bucketName = getBucketName(aemAssetsConfig.hostname);

  if (!assetId || !bucketName) {
    return res.status(400).json({ error: "Missing AEM Information" });
  }

  // Get the access token from the session
  const accessToken = req.session.accessToken;

  if (!accessToken) {
    return res.status(401).json({ error: "Not Authenticated with Adobe IMS" });
  }

  try {
    const assetMetadata = await invokeGetAssetMetadataAPI(
      bucketName,
      assetId,
      accessToken
    );

    const filteredMetadata = getFilteredMetadata(JSON.parse(assetMetadata));
    res.status(200).json(filteredMetadata);
  } catch (error) {
    console.error("Error getting asset metadata:", error.message);
    res.status(500).json({ error: `Internal Server Error: ${error.message}` });
  }
});

// Helper function to invoke the AEM API to get asset metadata
async function invokeGetAssetMetadataAPI(bucketName, assetId, accessToken) {
  const apiUrl = `https://${bucketName}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`;


  // For debugging purposes
  console.log("API URL:", apiUrl);
  console.log("Access Token:", accessToken);
  console.log("API Key:", adobeADCConfig.clientId);

  try {
    const response = await fetch(apiUrl, {
      method: "GET",
      headers: {
        "If-None-Match": "string",
        "X-Adobe-Accept-Experimental": "1",
        Authorization: `Bearer ${accessToken}`,
        "X-Api-Key": adobeADCConfig.clientId,
      },
    });

    console.log("Response Status:", response.status);

    if (!response.ok) {
      throw new Error(`AEM API Error: ${response.statusText}`);
    }

    return await response.text();
  } catch (error) {
    throw new Error(`Failed to fetch asset metadata: ${error.message}`);
  }
}

// Helper function to filter the metadata properties like pim: and dc:
function getFilteredMetadata(data) {
  if (!data || !data.assetMetadata) {
    throw new Error("Invalid metadata structure received from API");
  }

  const properties = data.assetMetadata;
  return Object.keys(properties).reduce((filtered, key) => {
    if (
      key.startsWith("pim:") ||
      key === "dc:title" ||
      key === "dc:description"
    ) {
      filtered[key] = properties[key];
    }
    return filtered;
  }, {});
}

// API Route: Update AEM Asset Metadata
router.post("/api/updateAEMAssetMetadata", async (req, res) => {
  const { assetId, metadata } = req.body;

  if (!assetId || !metadata || typeof metadata !== "object") {
    return res.status(400).json({ error: "Invalid or Missing Metadata" });
  }

  const bucketName = getBucketName(aemAssetsConfig.hostname);
  if (!bucketName) {
    return res.status(400).json({ error: "Missing AEM Information" });
  }

  const accessToken = req.session.accessToken;
  if (!accessToken) {
    return res.status(401).json({ error: "Not Authenticated with Adobe IMS" });
  }

  try {
    const updatedMetadata = await invokePatchAssetMetadataAPI(
      bucketName,
      assetId,
      metadata,
      accessToken
    );
    res.status(200).json(updatedMetadata);
  } catch (error) {
    console.error("Error updating asset metadata:", error.message);
    res.status(500).json({ error: `Internal Server Error: ${error.message}` });
  }
});

// Helper function to invoke the AEM API to update asset metadata
async function invokePatchAssetMetadataAPI(
  bucketName,
  assetId,
  metadata,
  accessToken
) {
  const apiUrl = `https://${bucketName}.adobeaemcloud.com/adobe/assets/${assetId}/metadata`;
  const headers = {
    "Content-Type": "application/json-patch+json",
    "If-Match": "*",
    "X-Adobe-Accept-Experimental": "1",
    Authorization: `Bearer ${accessToken}`,
    "X-Api-Key": adobeADCConfig.clientId,
  };

  try {
    const response = await fetch(apiUrl, {
      method: "PATCH",
      headers,
      body: JSON.stringify(getTransformedMetadata(metadata)),
    });

    if (!response.ok) {
      throw new Error(`AEM API Error: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    throw new Error(`Failed to update asset metadata: ${error.message}`);
  }
}

// Helper function to transform metadata into JSON Patch format, e.g. [{ op: "add", path: "dc:title", value: "New Title" }]
function getTransformedMetadata(metadata) {
  return Object.keys(metadata).map((key) => ({
    op: "add",
    path: `/${key}`,
    value: metadata[key],
  }));
}

As chamadas da API do AEM baseadas em OpenAPI são feitas do lado do servidor (middleware expresso) e não diretamente do lado do cliente (navegador) para garantir que o token de acesso seja gerenciado com segurança e não exposto ao lado do cliente.

Atualizar o token de acesso

Para atualizar o token de acesso antes que ele expire, você pode implementar o fluxo do token de atualização. No entanto, para manter o tutorial simples, o aplicativo Web WKND-PIM não implementa o fluxo de token de atualização.

Configurar e executar o aplicativo Web

Vamos configurar e executar o aplicativo Web WKND-PIM no computador local para entender o fluxo de autenticação do aplicativo Web OAuth e as chamadas de API.

Pré-requisitos

Para concluir este tutorial, você precisa:

Etapas de desenvolvimento

As etapas de desenvolvimento de alto nível são:

Configurar projeto ADC

A etapa de configuração do Projeto ADC é repetida das APIs do AEM baseadas em OpenAPI de Instalação. É repetido adicionar a API do autor do Assets e configurar seu método de autenticação como OAuth Web App.

Configurar instância do AEM para habilitar a comunicação do Projeto ADC

Siga as instruções do artigo Configurar APIs do AEM baseadas em OpenAPI para configurar a instância do AEM para habilitar a comunicação do Projeto ADC.

Criar e aplicar o esquema de metadados de ativos

Por padrão, o projeto WKND Sites não tem o esquema de metadados de ativos necessário para exibir os atributos do produto. Vamos criar e aplicar o esquema de metadados de ativos a uma pasta de ativos na instância do AEM.

Em seguida, vamos criar o esquema de metadados específico do atributo PIM e aplicá-lo à pasta PIM.

Com as etapas acima, os ativos da pasta PIM estão prontos para armazenar os metadados de atributos do produto.

Configure e execute o aplicativo Web WKND-PIM

Verificar o fluxo de ponta a ponta

Revisar o código do aplicativo

Vamos analisar a estrutura de código de alto nível e os principais pontos de entrada do aplicativo Web WKND-PIM. O aplicativo é desenvolvido usando Node.js + Express.

Você pode desenvolver ou integrar o aplicativo web existente com as APIs do Adobe usando outras tecnologias do lado do servidor, como Java, Python ou .NET.

Resumo

Neste tutorial, você aprendeu a chamar APIs do AEM baseadas em OpenAPI no AEM as a Cloud Service a partir de um aplicativo web personalizado usando a autenticação do aplicativo web OAuth. Você analisou os trechos de código-chave usados no aplicativo Web WKND-PIM para entender o fluxo de autenticação do aplicativo Web OAuth.

Você pode usar o tutorial como referência para integrar as APIs do AEM baseadas em OpenAPI aos seus aplicativos Web personalizados, a fim de fornecer fluxos de trabalho eficientes e centrados no usuário.

Recursos adicionais