Acessar dados do SharePoint a partir de suplementos usando a biblioteca de domínio cruzado

  • Artigo

Quando você cria Suplementos do SharePoint, geralmente é necessário incorporar dados de várias fontes. Mas por motivos de segurança, os mecanismos de bloqueio impedem a comunicação com mais de um domínio por vez. Esses mecanismos de segurança são implementados na maioria dos navegadores, dificultando ou impossibilitando a realização de chamadas pelo cliente entre domínios.

Quando um usuário solicita uma página do seu domínio de suplemento, a comunicação do lado do cliente é vinculada somente a esse domínio. Seu suplemento pode emitir chamadas do cliente da página somente para outros recursos no mesmo domínio. No entanto, os suplementos geralmente exigem recursos de outros domínios, como o domínio do SharePoint, para preencher seus cenários. No código da sua página, você pode tentar emitir uma solicitação para o domínio do SharePoint, que é bloqueado pelo navegador. Você geralmente vê um erro Acesso negado. O erro não implica que você não tenha permissões para os recursos solicitados, mas, muito provavelmente, você não pode sequer emitir uma solicitação para os recursos mencionados.

Quando você usa a biblioteca de domínio cruzado, as páginas da Web no seu suplemento podem acessar dados no seu domínio de suplemento e no domínio do SharePoint. A biblioteca de domínio cruzado é uma alternativa do cliente na forma de um arquivo JavaScript (SP.RequestExecutor.js) hospedado no site do SharePoint que você pode referenciar em seu suplemento remoto. A biblioteca de domínio cruzado permite que você interaja com mais de um domínio em sua página de suplemento remoto por meio de um proxy. É uma boa opção se você quiser que seu código de suplemento seja executado no cliente, e não no servidor, e se houver barreiras de conectividade, como firewalls, entre o SharePoint e sua infraestrutura remota.

Você pode acessar dados no host da Web — por exemplo, pode acessar listas com as quais os usuários finais interagem, independentemente do seu suplemento. Ou você pode acessar dados nos sites do suplemento, como listas provisionadas especificamente para o seu suplemento. Os suplementos também podem acessar outros conjuntos de sites e sites, desde que o suplemento tenha permissões de escopo de locatário e tenha sido implantado como uma instalação em lotes usando o catálogo de suplementos.

Observação

Neste tópico, o domínio de suplemento refere-se ao domínio que hospeda as páginas de suplemento. Esse pode ser o domínio de um aplicativo Web remoto em um suplemento hospedado pelo provedor, mas as páginas suplementares também podem estar no SharePoint nos sites do suplemento e fazer chamadas para o domínio do host da Web. No segundo cenário, o domínio do suplemento é o domínio dos sites do suplemento.

O principal exemplo deste artigo mostra como criar um suplemento que lê dados nos sites do suplemento e os exibe em uma página da Web. A seção Próximas etapas mostra mais cenários criados com base no exemplo principal.

Pré-requisitos

Para seguir os exemplos deste artigo, você precisa do seguinte:

Ler os dados sobre sites do suplemento usando a biblioteca entre domínios

Neste exemplo, há uma página simples hospedada fora do SharePoint que usa um ponto de extremidade REST (Representational State Transfer) para ler os dados em um site do SharePoint (site do suplemento). Como a biblioteca de domínio cruzado requer um site do suplemento, faz sentido começar com esse cenário.

Para ler os dados de sites do suplemento, faça o seguinte:

  1. Crie um Suplemento do SharePoint e projetos da Web.

  2. Crie itens de lista em sites do suplemento. Essa etapa também garante que sites do suplemento sejam criados quando os usuários implantarem o suplemento.

  3. Crie uma página de suplemento que usa a biblioteca entre domínios para ler os itens da lista.

A figura a seguir mostra uma página da Web que exibe os dados em sites do suplemento.

Tela de resultados de exemplo para itens de leitura entre domínios

Para criar um Suplemento do SharePoint e projetos da Web

  1. Abra o Visual Studio como administrador. (Para isso, clique com o botão direito do mouse no ícone do Visual Studio no menu Iniciar e selecione Executar como administrador.)

  2. Crie um novo projeto usando o modelo Suplemento para SharePoint. O modelo Suplemento para SharePoint no Visual Studio está localizado em Modelos > Visual C# > Office SharePoint > Suplementos.

  3. Forneça a URL do site do SharePoint que você deseja usar para depuração.

  4. Selecione Hospedado pelo provedor como a opção de hospedagem para o suplemento.

    Observação

    Você também pode usar a biblioteca de domínio cruzado em um suplemento hospedado pelo SharePoint. No entanto, em um suplemento hospedado do SharePoint, a página de suplemento já está nos sites do suplemento, caso em que não seria necessário a biblioteca de domínio cruzado para ler os itens da lista. Para um exemplo de suplemento hospedado pelo SharePoint que lê dados no host da Web, confira Usar a biblioteca de domínio cruzado em um suplemento hospedado pelo SharePoint (REST) ou Acessar dados do host da Web mais adiante neste artigo.

Para criar itens de lista nos sites do suplemento

  1. Clique com o botão direito do mouse no projeto Suplemento do SharePoint no Gerenciador de Soluções. Selecione Adicionar > Novo Item.

  2. Selecione Itens do Visual C# > Office/SharePoint > Lista. Configure o nome da sua lista como Anúncios.

  3. Clique duas vezes em Anúncios > Elements.xml. Cole os seguintes nós XML como filhos do elemento ListInstance.

    <Data>
    <Rows>
        <Row>
            <Field Name="Title">Lorem ipsum 1</Field>
            <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
        </Row>
        <Row>
            <Field Name="Title">Lorem ipsum 2</Field>
            <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
        </Row>
    </Rows>
</Data>

Para criar uma página de suplemento que usa a biblioteca de domínio cruzado

  1. Clique duas vezes em Default.aspx no projeto Web no Gerenciador de Soluções.

  2. Copie o seguinte código e cole-o no arquivo Default.aspx. O código executa as seguintes tarefas:

    • Carrega a biblioteca jQuery da CDN da Microsoft.

    • Fornece um espaço reservado para o resultado.

    • Extrai a URL de sites do suplemento da cadeia de consulta.

    • Carrega o JavaScript da biblioteca de domínio cruzado usando a função getScript no jQuery.

      A função carrega os recursos necessários e vai para a função especificada, garantindo que a biblioteca entre domínios seja carregada e esteja disponível para uso pelo código subsequente.

    • Cria uma instância do objeto RequestExecutor. Por padrão, RequestExecutor usa sites do suplemento como o site de contexto.

      Observação

      (REST) ou objeto (JSOM). Para saber mais sobre o AppContextSite, confira Acessar dados do host da Web mais adiante neste artigo.

    • Emite uma chamada REST para o ponto de extremidade de itens de lista.

    • Lida com a conclusão bem-sucedida, exibindo os itens de lista na página da Web.

    • Lida com erros, exibindo a mensagem de erro na página da Web.

  
<html>
    <head>
        <title>Cross-domain sample</title>
    </head>
    <body>
        <!-- This is the placeholder for the announcements -->
        <div id="renderAnnouncements"></div>
        <script 
            type="text/javascript" 
            src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
        </script>
        <script type="text/javascript">
          var hostweburl;
          var appweburl;

          // Load the required SharePoint libraries
          $(document).ready(function () {
            //Get the URI decoded URLs.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
            appweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPAppWebUrl")
            );

            // resources are in URLs in the form:
            // web_url/_layouts/15/resource
            var scriptbase = hostweburl + "/_layouts/15/";

            // Load the js files and continue to the successHandler
            $.getScript(scriptbase + "SP.RequestExecutor.js", execCrossDomainRequest);
          });

          // Function to prepare and issue the request to get
          //  SharePoint data
          function execCrossDomainRequest() {
            // executor: The RequestExecutor object
            // Initialize the RequestExecutor with the add-in web URL.
            var executor = new SP.RequestExecutor(appweburl);

            // Issue the call against the add-in web.
            // To get the title using REST we can hit the endpoint:
            //      appweburl/_api/web/lists/getbytitle('listname')/items
            // The response formats the data in the JSON format.
            // The functions successHandler and errorHandler attend the
            //      sucess and error events respectively.
            executor.executeAsync(
                {
                  url:
                      appweburl +
                      "/_api/web/lists/getbytitle('Announcements')/items",
                  method: "GET",
                  headers: { "Accept": "application/json; odata=verbose" },
                  success: successHandler,
                  error: errorHandler
                }
            );
          }

          // Function to handle the success event.
          // Prints the data to the page.
          function successHandler(data) {
            var jsonObject = JSON.parse(data.body);
            var announcementsHTML = "";

            var results = jsonObject.d.results;
            for (var i = 0; i < results.length; i++) {
              announcementsHTML = announcementsHTML +
                  "<p><h1>" + results[i].Title +
                  "</h1>" + results[i].Body +
                  "</p><hr>";
            }

            document.getElementById("renderAnnouncements").innerHTML =
                announcementsHTML;
          }

          // Function to handle the error event.
          // Prints the error message to the page.
          function errorHandler(data, errorCode, errorMessage) {
            document.getElementById("renderAnnouncements").innerText =
                "Could not complete cross-domain call: " + errorMessage;
          }

          // Function to retrieve a query string value.
          // For production purposes you may want to use
          //  a library to handle the query string.
          function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&amp;");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
              var singleParam = params[i].split("=");
              if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
            }
          }
        </script>
    </body>
</html>

Para compilar e executar a solução

  1. Pressione a tecla F5.

    Observação

    Ao pressionar F5, o Visual Studio compila a solução, implanta o suplemento e abre a página de permissões do suplemento.

  2. Selecione o botão Confiar.

  3. Selecione o ícone de suplemento na página Conteúdo do Site.

Se preferir exemplos de código para download, você pode obter o seguinte na galeria de códigos:

Resolver problemas da solução

Se você observar esta mensagem de erro… Experimente…
"Tivemos alguns problemas para acessar seu site. Também há um botão para corrigir o erro, mas ele não corrige o problema." Você pode ter um problema conhecido com zonas de segurança no Internet Explorer; confira Trabalhar com a biblioteca de domínio cruzado entre diferentes zonas de segurança do Internet Explorer em Suplementos do SharePoint.
"As funcionalidades necessárias não têm suporte pelo seu navegador. Verifique se você está usando o IE 8 ou superior, ou outro navegador moderno. Certifique-se de que a meta tag 'X-UA-Compatible' esteja configurada para 'IE=8' ou superior." A biblioteca de domínios cruzados= requer um modo de documento de IE8 ou posterior. Em alguns cenários, o modo de documento é definido como IE7 por padrão. Você pode usar as ferramentas do desenvolvedor do Internet Explorer para determinar e alterar o modo de documento da sua página. Para obter mais informações, confira Definir a compatibilidade de documentos.
'Type' está indefinido. Além disso, o suplemento usa o JavaScript Object Model (JSOM). O JSOM usa o método Type.registerNamespace na biblioteca do Microsoft Ajax para registrar o namespace SP. Use o código a seguir para adicionar uma referência à biblioteca do Microsoft Ajax na página:

HTML <script type="text/javascript" src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>

Próximas etapas: mais cenários de biblioteca de domínio cruzado

Este artigo mostra como consultar um ponto de extremidade REST para ler os dados de sites do suplemento usando uma página de suplemento que não está hospedada no SharePoint. Você também pode explorar os cenários e detalhes a seguir sobre a biblioteca entre domínios.

Usar o JSOM para ler os dados de sites do suplemento

Dependendo de sua preferência, convém usar JSOM em vez de REST para consultar dados de sites do suplemento. Você deve concluir tarefas adicionais para usar a biblioteca entre domínios com JSOM:

  • Faça referência ao JSOM do SharePoint na página de suplementos.

  • Inicialize o objeto ProxyWebRequestExecutorFactory e defina-o como a fábrica do objeto de contexto.

  • Acesse os objetos do SharePoint para ler os dados da lista.

  • Carregue os objetos no contexto e execute a consulta.

Para um exemplo de código que mostra como executar as tarefas, confira SharePoint-Add-in-JSOM-CrossDomain.

Para obter mais informações sobre como usar o JSOM, confira Usar o modelo de objeto JavaScript (JSOM) em suplementos para o SharePoint.

Acessar dados do host da Web

O exemplo nesta página mostra como ler dados de sites do suplemento. Isso funciona bem como o exemplo inicial, pois a biblioteca de domínio cruzado usa inicialmente o suplemento como o site de contexto. No entanto, existem muitos cenários em que você deseja acessar dados no host da Web. Algumas tarefas são necessárias para acessar dados no host da Web:

  • Defina o host da Web como o site de contexto para a biblioteca entre domínios.

  • Forneça permissões apropriadas para o suplemento.

Você pode alterar o site de contexto usando o ponto de extremidade AppContextSite (REST) ou o objeto (JSOM). O exemplo a seguir mostra como alterar o site de contexto usando o ponto de extremidade REST:

executor.executeAsync(
    {
        url:
            appweburl +
            "/_api/SP.AppContextSite(@target)/web/title?@target='" +
            hostweburl + "'",
        method: "GET",
        headers: { "Accept": "application/json; odata=verbose" },
        success: successHandler,
        error: errorHandler
    }
);

O seguinte exemplo mostra como alterar o site de contexto usando JSOM:

context = new SP.ClientContext(appweburl);
factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
context.set_webRequestExecutorFactory(factory);
appContextSite = new SP.AppContextSite(context, hostweburl);

this.web = appContextSite.get_web();
context.load(this.web);

Por padrão, o suplemento tem permissões para sites do suplemento, mas não para o host da Web. O exemplo a seguir mostra uma seção de manifesto que declara uma solicitação de permissão para ler os dados do host da Web:

<AppPermissionRequests>
    <AppPermissionRequest 
        Scope="http://sharepoint/content/sitecollection/web" 
        Right="Read" />
</AppPermissionRequests>

Assegure-se de criar um recurso em sites do suplemento (como uma lista ou página vazias) para forçar o provisionamento de sites do suplemento, que é necessário para usar a biblioteca entre domínios.

Acessar dados entre conjuntos de sites

Com a biblioteca entre domínios, você pode acessar dados entre conjuntos de sites no mesmo locatário. Há algumas tarefas que você precisa concluir para acessar dados entre conjuntos de sites:

  • Adicione uma solicitação de permissão para acessar dados no locatário.

  • No código, alterne o site de contexto para os conjuntos de sites que você deseja consultar.

  • Adicione o suplemento ao catálogo de suplementos.

  • Implante o suplemento com escopo de locatário para um site. Para obter um exemplo de como implantar como um suplemento com escopo de locatário, consulte a descrição do exemplo de código de Usar a biblioteca entre domínios em um suplemento com escopo de locatário (REST).

O suplemento também precisa de permissão para acessar dados do locatário. O exemplo a seguir mostra uma seção de manifesto que declara uma solicitação de permissão para ler dados do locatário:

<AppPermissionRequests>
  <AppPermissionRequest 
    Scope="http://sharepoint/content/tenant" 
    Right="Read" />
</AppPermissionRequests>

Para alternar o site de contexto em seu código, use o ponto de extremidade AppContextSite (REST) ou o objeto (JSOM), assim como na seção Acessar dados do host da Web.

Aqui está um lembrete do ponto de extremidade REST: /_api/SP.AppContextSite(@target)/web/title?@target='weburl', e um exemplo de como criar uma instância do objeto em JSOM: appContextSite = new SP.AppContextSite(context, weburl);.

Como desenvolvedor, você só pode implantar suplementos com escopo de locatário no catálogo de suplementos. Você pode provisionar um catálogo de suplementos para seus ambientes locais ou do SharePoint Online. Fazer o upload do seu suplemento no catálogo de complementos é tão simples quanto fazer o upload de um arquivo para uma biblioteca de documentos. Para obter instruções detalhadas, confira Usar o catálogo de aplicativos para criar aplicativos corporativos personalizados disponíveis para seu ambiente do SharePoint Online.

No catálogo de suplementos, você pode implantar o suplemento em um ou mais sites no locatário. Como o seu suplemento tem permissões para acessar dados no locatário, você só precisa implantar em um site para acessar os dados de todo o locatário. Para obter instruções sobre como implantar um suplemento do catálogo de suplementos, confira Implantar um suplemento personalizado

Para baixar um exemplo de código que mostra como acessar dados entre conjuntos de sites, consulte Usar a biblioteca entre domínios em um suplemento com escopo de locatário (REST).

Emitir chamadas entre zonas de segurança diferentes

A biblioteca de domínio cruzado usa uma página de proxy hospedada em um IFrame na página do suplemento para ativar a comunicação. Quando a página de suplemento e o site do SharePoint estiverem em zonas de segurança diferentes, os cookies de autorização não poderão ser enviados. Se não houver cookies de autorização e o IFrame tentar carregar a página do proxy, ela será redirecionada para a página de entrada do SharePoint. A página de entrada do SharePoint não pode estar contida em um IFrame por motivos de segurança. Nesses cenários, a biblioteca não pode carregar a página do proxy e a comunicação com o SharePoint não é possível.

No entanto, há uma solução para esses cenários. A solução é o padrão apphost, que consiste em colocar as páginas de suplemento em uma página hospedada no site do suplemento. É uma boa ideia usar o padrão apphost em suplementos que usam a biblioteca entre domínios, mesmo se não houver limites de segurança evidentes. Para saber mais, consulte Trabalhar com a biblioteca entre domínios entre diferentes zonas de segurança do Internet Explorer em Suplementos do SharePoint.

Acessar dados de um host remoto adicional em um suplemento hospedado pelo SharePoint

Por padrão, um suplemento hospedado pelo SharePoint tem permissão para emitir chamadas entre domínios no host da Web, desde que tenha permissões adequadas. No entanto, um suplemento hospedado pelo SharePoint também pode especificar um host remoto no atributo AllowedRemoteHostUrl de seu AppPrincipal. Isso efetivamente permite emitir chamadas entre domínios do site do suplemento e de outro host em outro lugar.

Para baixar um exemplo de um suplemento hospedado pelo SharePoint que usa a biblioteca entre domínios, confira Exemplo de código: usar a biblioteca entre domínios em um suplemento hospedado pelo SharePoint (REST).

Confira também