Compartilhar via

Orientação de Inclusão para Fornecedores de API do OneRoster com o School Data Sync (SDS)

  • Artigo

Introdução

Microsoft School Data Sync (SDS) podem sincronizar informações de identidade e lista de todos os sistemas que implementem a norma 1EdTech OneRoster API (Application Programming Interfaces) num fluxo de dados de entrada. Este documento destina-se a ajudar os novos fornecedores de APIs do OneRoster a integrarem-se com êxito no SDS. Os clientes podem ligar-se diretamente ao fornecedor com as APIs oneRoster 1.1 baseadas em REST. O seguinte processo de inclusão define os passos exigidos pelo fornecedor de API antes de poderem ser adicionados para os inquilinos selecionarem e utilizarem no SDS.

Acerca do SDS

  • Se quiser saber mais sobre o SDS, aceda ao Site de Produto do SDS.

  • Para obter informações técnicas sobre o SDS, incluindo vídeos de implementação e orientações para administradores, aceda ao site de documentação do SDS.

  • Para obter mais informações sobre a experiência do cliente para ligar dados à API OneRoster, aceda a Ligar dados à API OneRoster.

Visão Geral

  1. Preencha o formulário no formulário de Inscrição de Parceiros do SDS.

    1. Indique que iria prestar assistência à Integração do School Data Sync no formulário.

    2. O registo é necessário para aceder ao formulário – visite o site do Microsoft Partner Network para obter mais informações. Tem de submeter um formulário separado para acesso a recursos de programador do Office e SDS.

  2. Implemente os pontos finais da API do OneRoster necessários para o SDS.

    O SDS utiliza um filtro na propriedade dateLastModified para processamento de sincronização delta/sincronização incremental e é necessário para integração com o SDS.

  3. Verifique se o SDS funciona com os pontos finais da API do OneRoster.

    1. Avalie as suas APIs com a coleção do Postman.

    2. Teste com a engenharia do SDS num ambiente de sandbox.

    3. Configure o SDS para validar a solução E2E.

  4. Pilote a solução com dois clientes de produção.

  5. Disponibilize o conector geralmente no SDS para todos os inquilinos Office 365 EDU.

Introdução

Pontos finais de API necessários para o SDS

Ação URL Propriedades de Filtro Necessárias Filtro Opcional/Recomendado Exemplos
GetAllAcademicSessions /academicSessions status dateLastModified /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}'
GetAllOrgs /orgs status dateLastModified /orgs?offset=0&limit=5000&filter=status='active'/orgs?filter=dateLastModified>'{deltaDateTime}'
GetAllUsers /users status dateLastModified /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}'
GetAllClasses /classes status dateLastModified /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments /enrollments status dateLastModified /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

Pontos Finais de API Opcionais para SDS

Observação

Para os dados opcionais para dados demográficos, relações de contacto de estudantes e sinalizadores de utilizadores de estudantes, a capacidade de um cliente incluir ou não estes dados será baseada nas capacidades de dados opcionais suportadas do seu perfil de fornecedor que iremos criar. Ao seguir os passos de teste e verificação indicados, se optar por também suportar estes dados para os seus clientes que estão a utilizar o SDS, estes verão o botão de alternar (predefinição) selecionado Como Ativado para incluir dados adicionais. Podem selecionar o botão de alternar para desativar, se assim o desejarem. Se o botão de alternar estiver indisponível, mostrado mas desativado e não estiver disponível para interação, significa que o perfil do fornecedor não suporta atualmente a disponibilização dos mesmos.

Ação URL Propriedades de Filtro Necessárias Filtro Opcional/Recomendado Exemplos
GetAllCourses /courses status dateLastModified /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics /demographics status dateLastModified /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

Relações de contacto opcionais do estudante do utilizador

Dica

Uma vez que o SDS não suporta o side loading da data dos contactos dos estudantes através do CSV se os dados da lista estiverem a ser fornecidos através da API do OneRoster, recomendamos que todos os fornecedores trabalhem para suportar o fornecimento de contactos através da abordagem da API OneRoster.

A relação de contacto dos estudantes pode ser especificada para os utilizadores estudantes melhorarem as experiências de educador para comunicação com os encarregados de educação e tutores dos estudantes. Os contactos são mais utilizadores que são fornecidos com o ponto final /users e a associação a um estudante encontram-se no registo de utilizador do estudante em "agentes".

  • Para obter mais informações, sobre as funções suportadas de Relações de Contacto de Estudantes suportadas pelo SDS, veja Lista predefinida de valores: Funções de Relação de Contacto.
  • familyName, givenName e e-mail são necessários para utilizadores que tenham funções de contacto/tutor.
  • Espera-se que o telefone e sms estejam na E.164 e + têm de ser incluídos. (Exemplo: +1234567890).
  • Se forem fornecidos dados inversos, de um registo guardião da relação de contacto para um estudante no campo "agentes" dos utilizadores de contacto, estes registos são filtrados.

Sinalizadores demográficos de utilizador opcionais

Os sinalizadores de utilizador podem ser especificados para os utilizadores estudantes indicarem a sua participação num programa ou coorte. Os sinalizadores de utilizador são incluídos (quando verdadeiro para o utilizador) ou não são incluídos se não forem aplicáveis.

Os sinalizadores são especificados como uma extensão de metadados para o utilizador, num campo de metadados. A abordagem segue uma Chave|Par de valores, com a chave com o nome microsoft.userFlags, e tem de ser formatado como uma lista delimitada por vírgulas. Os sinalizadores de utilizador podem aparecer por qualquer ordem e não são sensíveis às maiúsculas e minúsculas.

Para obter mais informações, na lista predefinida de valores de sinalizador de utilizador suportados pelo SDS, veja Lista predefinida de valores: Sinalizadores de Utilizador.

Exemplo:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

Regras de Correspondência e Validação de Dados

Para obter mais informações sobre a correspondência de dados e regras de validação, veja Regras de Validação e Descrições.

Importante

Por 1EdTech, é da responsabilidade do fornecedor impor a privacidade dos dados relativamente aos dados disponíveis quando é feito um pedido de dados. O School Data Sync faz um pedido de dados ativos com base na hora do pedido.

Notas e sugestões úteis

  • Os pontos finais são sempre apresentados a seguir ao URL https: {server_URL}/ims/oneroster/v1p1.
  • Todos os pontos finais têm de suportar a paginação, ou seja, limite e parâmetros de deslocamento (por exemplo: limite=10&offset=5000).
  • Os pontos finais têm requisitos no suporte de parâmetros de filtro para permitir a filtragem por status ou ativar a sincronização delta.
  • Os clientes sabem como ativar a opção "Está Ativo" ou como permitir que apenas os dados ativos estejam disponíveis para a ligação que vai ser utilizada pelo School Data Sync. Isto garante que apenas os dados ativos do Ano Letivo ativo e da sessão são fornecidos à medida que o ano letivo avança.
  • Para impedir que determinadas escolas sejam incluídas nos dados fornecidos do SIS para o SDS, os clientes sabem como configurar que escolas estão incluídas para a ligação/credenciais que estão a ser utilizadas para ligar o SDS ao respetivo SIS.
  • O SDS aplica um filtro na propriedade dateLastModified para processamento de sincronização delta/sincronização incremental e é necessário para a integração com o SDS.
  • Os fornecedores têm de optar por implementar o esquema de autenticação OAuth1(a) ou OAuth 2.0 (concessão de credenciais de cliente), o OAuth 2.0 preferencial.
  • Durante o desenvolvimento, pode verificar os pontos finais com a nossa coleção do Postman.
  • Se o protocolo de autenticação suportado for "OAuth 2" – tipo de concessão de credenciais de cliente, o SDS enviará as credenciais no Cabeçalho "Autorização". O SDS não suporta o envio das credenciais no corpo do pedido.

Testar as SUAS APIs do OneRoster

Utilizar a coleção do Postman

O Postman é uma ferramenta conhecida para executar e gerir APIs REST. Criámos a coleção do Postman da API do OneRoster para invocar e testar as APIs do OneRoster exigidas pelo SDS. A execução da coleção invoca todas as APIs necessárias pelo SDS e executa testes simples em relação aos dados devolvidos.

Testar com a Engenharia do SDS num ambiente de sandbox

Crie um ambiente de sandbox para as suas APIs do OneRoster e partilhe as credenciais com o engenheiro do SDS designado. Em conjunto, executamos um conjunto mais aprofundado de testes para garantir que a integração é bem-sucedida.

Configurar para validar a solução

Quando todos os testes forem concluídos com êxito, o nome do sistema é adicionado à lista de fornecedores do OneRoster no SDS. No entanto, neste momento, só é visível para inquilinos em voo para perfis de fornecedores indicados como sendo o modo "InPilot" (não disponível publicamente). Em seguida, configure o SDS para Ligar dados com a API OneRoster no seu inquilino de teste do Microsoft 365 para sincronizar dados a partir dos pontos finais do OneRoster do sandbox e garantir que as execuções são concluídas sem erros. Se vir erros ou avisos e precisar de ajuda após a sua auto-investigação, contacte o engenheiro do SDS designado.

Piloto do cliente

Assim que os testes tiverem sido concluídos com êxito, está na altura de começar a testar a solução com os clientes. O nome do seu sistema é visível na lista de fornecedores do OneRoster® no SDS para os "pilotos" para ver também os fornecedores que estão no modo "InPilot", concordando em pilotar a integração. A equipa do SDS e a equipa do fornecedor do OneRoster trabalham em conjunto para identificar os clientes piloto adequados e agendar uma hora para implementar o SDS. Colaboramos em estreita colaboração com os clientes para garantir que as execuções de fluxo de entrada são bem-sucedidas e validar os resultados em conjunto. Todos os erros finais identificados devem ser resolvidos antes de disponibilizar publicamente a solução a todos os clientes Office 365 educação.

Tornar público

Depois de dois clientes terem concluído com êxito as implementações piloto, o sistema de parceiros estará disponível no SDS como um sistema de origem de fornecedor certificado do OneRoster. O SDS apresenta o nome do fornecedor aos inquilinos quando definem a respetiva configuração de dados de ligação com a API OneRoster. A equipa do SDS documenta o sistema de parceiros na nossa página de descrição geral do fornecedor da API OneRoster nos nossos documentos online do SDS.

A equipa do SDS precisa:

  • Versão mínima do software
  • Pré-requisitos de configuração
  • Como obter o ID de Cliente, o Segredo do Cliente e os URLs
  • Quaisquer outras instruções específicas
  • Quem contactar para obter ajuda

A equipa do SDS pode coordenar-se com a sua equipa para promover a integração de forma mais abrangente através de vários canais de marketing.