Exemplos de API da Web (JavaScript do cliente)

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Este tópico fornece um entendimento comum sobre exemplos de API da Web usando JavaScript do cliente. Embora cada exemplo se concentre em um aspecto diferente da API da Web do Microsoft Dynamics 365, todos seguem processos e estruturas semelhantes descritos neste tópico.

Neste tópico

Exemplos de API da Web usando JavaScript do cliente

Como baixar o código-fonte do exemplo.

Como importar a solução Dynamics 365 que contém o exemplo.

Como executar o exemplo para ver o scripts em ação

Elementos comuns encontrados em cada exemplo

Exemplos de API da Web usando JavaScript do cliente

Os seguintes exemplos usam os padrões descritos aqui:

Amostra

Grupo de exemplo

Descrição

Exemplo de operações básicas da API Web (JavaScript do lado do cliente)

Amostra de operações básicas API da Web

Demonstra como criar, recuperar, atualizar, excluir, associar e desassociar registros da entidade do Dynamics 365.

Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)

Exemplo de dados de consulta de API da Web

Demonstra como usar funções e sintaxe de consulta OData v4, bem como funções de consulta do Microsoft Dynamics 365. Inclui uma demonstração de trabalho com consultas predefinidas e uso de FetchXML para realizar consultas.

Exemplo de operações condicionais da API Web (JavaScript do lado do cliente)

Amostra de operações de condição de API da Web

Demonstra como realizar operações condicionais. O comportamento dessas operações depende de critérios especificados por você.

Funções da API Web e Amostra de ações (Javascript do cliente)

Exemplo de funções API da Web e ações

Demonstra como usar as funções e as ações associadas e não associadas, incluindo ações personalizadas.

Como baixar o código-fonte do exemplo.

O código fonte de cada exemplo está disponível na Galeria de Códigos do MSDN O link para baixar cada exemplo está incluído na página individual desse exemplo.

Após baixar o exemplo, extraia o arquivo compactado. Encontre a solução Visual Studio 2015 de cada exemplo na pasta C#, já que o projeto é um projeto de aplicativo da Web ASP.NET vazio. No download, também é fornecida uma solução Dynamics 365 que você pode importar e executar.

Observação

Nem Microsoft Visual Studio nem ASP.NET são necessários para desenvolver JavaScript do cliente para Dynamics 365; porém, o site da Galeria de Códigos do MSDN requer que arquivos sejam incluídos em um Microsoft Visual Studio como um contêiner. No entanto, Microsoft Visual Studio fornece uma boa experiência para escrever JavaScript.

Como importar a solução Dynamics 365 que contém o exemplo.

Em cada projeto, você encontrará um arquivo de solução gerenciada do Microsoft Dynamics 365. O nome desse arquivo dependerá do nome de projeto do exemplo, mas o nome do arquivo terminará com _managed.zip.

Para importar a solução Dynamics 365 para seu servidor do Dynamics 365, faço o seguinte:

  1. Extraia o conteúdo do arquivo .zip baixado e localize o arquivo da solução Dynamics 365, que também será um arquivo .zip. Por exemplo, se você baixar o exemplo Basic Operations, procure o arquivo .zip da solução Dynamics 365 com o nome WebAPIBasicOperations\WebAPIBasicOperations_1_0_0_0_managed.zip.

  2. Na interface de usuário do Dynamics 365, acesse Configurações > Soluções. Essa página lista todas as soluções no seu servidor do Dynamics 365. Após concluir a importação dessa solução, o nome da solução para esse exemplo aparecerá nessa lista (por exemplo, Operações básicas de API da Web).

  3. Clique em Importar e siga as instruções no diálogo de importação para concluir essa ação.

Como executar o exemplo para ver o scripts em ação

O programa de exemplo é executado com um recurso da Web no Dynamics 365. A solução importada fornece uma página de configuração que dá a você uma opção para manter ou excluir os dados de exemplo e um botão para iniciar o programa de exemplo. No caso do exemplo Basic Operations, essa interface é semelhante ao que se segue:

Dynamics 365 Web API Sample Configuration page

Para executar o exemplo, faça o seguinte:

  1. Na página Todas as soluções no Dynamics 365, clique no nome da solução (por exemplo, o link Operações básicas de API da Web). Isso abrirá as propriedades da solução em uma nova janela.

  2. No menu de navegação à esquerda, clique em Configuração.

  3. Clique no botão Iniciar exemplo para executar o código de exemplo.

Elementos comuns encontrados em cada exemplo

A seguinte lista destaca alguns elementos comuns encontrados em cada um desses exemplos.

  • A função Sdk.startSample é chamada quando um usuário clica no botão Iniciar exemplo na página HTML. A função Sdk.startSample inicializa variáveis globais e começa a primeira operação na cadeia.

  • As mensagens de erros e saída do programa são enviadas ao console depurador do navegador. Para ver essa saída, abra a janela do console primeiro antes de executar o exemplo. Pressione F12 para acessar as ferramentas de desenvolvedor, incluindo a janela do console, nos navegadores Windows Internet Explorer e Microsoft Edge.

  • Esses exemplos usam a implementação ES6-Promise nativa do navegador para navegadores modernos que são compatíveis com ela. No caso do Internet Explorer 11, esse exemplo usa o polyfill de ES6-Promise porque o Internet Explorer 11 é o único navegador compatível com o Microsoft Dynamics 365 que não tem suporte nativo para esse recurso.

    Promessas não são necessários. Interações semelhantes podem ser realizadas por meio de funções de retorno de chamada. Para obter mais informações, consulte Criar uma função reutilizável usando retornos de promessas.

  • A função Sdk.request administra a solução com base nas informações transmitidas como parâmetros. Dependendo da necessidade de cada exemplo, os parâmetros transmitidos podem ser diferentes. Consulte o código-fonte desse exemplo para obter mais detalhes.

    /**
 * @function request
 * @description Generic helper function to handle basic XMLHttpRequest calls.
 * @param {string} action - The request action. String is case-sensitive.
 * @param {string} uri - An absolute or relative URI. Relative URI starts with a "/".
 * @param {object} data - An object representing an entity. Required for create and update actions.
 * @returns {Promise} - A Promise that returns either the request object or an error object.
 */
Sdk.request = function (action, uri, data) {
    if (!RegExp(action, "g").test("POST PATCH PUT GET DELETE")) { // Expected action verbs.
        throw new Error("Sdk.request: action parameter must be one of the following: " +
            "POST, PATCH, PUT, GET, or DELETE.");
    }
    if (!typeof uri === "string") {
        throw new Error("Sdk.request: uri parameter must be a string.");
    }
    if ((RegExp(action, "g").test("POST PATCH PUT")) && (data === null || data === undefined)) {
        throw new Error("Sdk.request: data parameter must not be null for operations that create or modify data.");
    }

    // Construct a fully qualified URI if a relative URI is passed in.
    if (uri.charAt(0) === "/") {
        uri = clientUrl + webAPIPath + uri;
    }

    return new Promise(function (resolve, reject) {
        var request = new XMLHttpRequest();
        request.open(action, encodeURI(uri), true);
        request.setRequestHeader("OData-MaxVersion", "4.0");
        request.setRequestHeader("OData-Version", "4.0");
        request.setRequestHeader("Accept", "application/json");
        request.setRequestHeader("Content-Type", "application/json; charset=utf-8");
        request.onreadystatechange = function () {
            if (this.readyState === 4) {
                request.onreadystatechange = null;
                switch (this.status) {
                    case 200: // Success with content returned in response body.
                    case 204: // Success with no content returned in response body.
                        resolve(this);
                        break;
                    default: // All other statuses are unexpected so are treated like errors.
                        var error;
                        try {
                            error = JSON.parse(request.response).error;
                        } catch (e) {
                            error = new Error("Unexpected Error");
                        }
                        reject(error);
                        break;
                }

            }
        };
        request.send(JSON.stringify(data));
    });
};

    A função Sdk.request retorna uma promessa. Quando a solução envolvida pela promessa é concluída, a promessa é resolvida ou rejeitada. Se for resolvida, a função no seguinte método then será chamada. Se for rejeitada, a função no seguinte método catch será chamada. Se a função no método then em si retornar uma promessa, a cadeia de operações nos métodos consecutivos then poderá continuar. Retornar uma promessa permite que encadeemos essas operações de exemplo juntas de uma forma que é preferida por muitos desenvolvedores para funções tradicionais de retorno de chamada. Para obter mais informações sobre promessas, consulte Promessa no JavaScript.

Confira Também

Use a API da Web do Microsoft Dynamics 365
Exemplos de API Web
Exemplos de API Web (C#)
Exemplo de operações básicas da API Web (JavaScript do lado do cliente)
Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)
Amostra de operações de condição de API da Web
Funções da API Web e Amostra de ações (Javascript do cliente)

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais