Share via

Diretrizes de integração para provedores de API do OneRoster com SDS (Sincronização de Dados Escolares)

  • Artigo

Introdução

Microsoft School Data Sync (SDS) pode sincronizar informações de identidade e lista de qualquer sistema que implemente o padrão 1EdTech OneRoster API (Interfaces de Programação de Aplicativo) em um fluxo de dados de entrada. Este documento destina-se a ajudar todos os novos provedores de APIs OneRoster a se integrarem com êxito ao SDS. O processo de integração a seguir define as etapas exigidas pelo provedor de API antes que eles possam ser adicionados para que os locatários selecionem e usem no SDS.

Sobre SDS

Visão Geral

  1. Conclua o formulário no formulário de inscrição do Parceiro SDS.

    1. Indique que você faria a assistência de Integração de Sincronização de Dados Escolar no formulário.

    2. O registro é necessário para acessar o formulário – visite o site da Microsoft Partner Network para obter mais informações. Você deve enviar um formulário separado para acesso a recursos de desenvolvimento do SDS e do Office.

  2. Implemente os pontos de extremidade da API do OneRoster exigidos pelo SDS.

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

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

    1. Avalie suas APIs usando a coleção Postman.

    2. Teste com a engenharia do SDS em um ambiente de área restrita.

    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 no SDS para todos os locatários Office 365 EDU.

Guia de Introdução

Pontos de extremidade de API necessários para 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 /Usuários 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 /Inscrições status Datelastmodified /enrollments?offset=0&limit=5000&filter=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

Pontos de extremidade de API opcionais para SDS

Observação

Para as partes opcionais de dados para demografia, relações de contato do aluno e sinalizadores de usuário do aluno, a capacidade de um cliente incluir esses dados ou não será baseada nos recursos de dados opcionais compatíveis do seu perfil de provedor que criaremos. Seguindo as etapas de teste e verificação anotadas, se você optar por também dar suporte a esses dados para seus clientes que estão usando o SDS, eles verão o alternância (padrão) selecionado em para incluir dados adicionais. Eles podem selecionar o alternância para desativar, se desejarem. Se a alternância não estiver disponível, mostrada, mas desativada e não estiver disponível para interação, isso significa que o perfil do provedor não dá suporte atualmente ao fornecimento dos dados.

Ação URL Propriedades de filtro necessárias Filtro opcional/recomendado Exemplos
GetAllCourses /Cursos status Datelastmodified /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics /Demografia status Datelastmodified /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

Relações de contato do aluno de usuário opcional

A relação de contato do aluno pode ser especificada para que os usuários dos alunos aprimorem as experiências do educador para comunicação com os pais e responsáveis dos alunos. Os contatos são mais usuários fornecidos com os /usuários e a associação a um aluno são encontrados no registro de usuário do aluno em 'agentes'.

  • Para obter mais informações, nas funções de Relação de Contato do Aluno com suporte do SDS, confira Lista padrão de valores: Funções de relacionamento de contato.
  • familyName, givenName e email são necessários para usuários que têm funções de contato/guardião.
  • Espere que o telefone e o SMS estejam no E.164 e + devem ser incluídos. (Exemplo: +1234567890).
  • Se dados inversos forem fornecidos, de um registro guardião de relação de contato para o aluno no campo "agentes" dos usuários de contato, esses registros serão filtrados.

Sinalizadores demográficos de usuário opcionais

Os sinalizadores de usuário podem ser especificados para que os usuários do aluno indiquem sua participação em um programa ou coorte. Os sinalizadores de usuário são incluídos (quando verdadeiros para o usuário) ou não são incluídos se não for aplicável.

Os sinalizadores são especificados como uma extensão de metadados para o usuário, em um campo de metadados, seguindo uma Chave|Par de valores, com a chave chamada microsoft.userFlags e deve ser formatada como uma lista delimitada por vírgulas. Os sinalizadores de usuário podem aparecer em qualquer ordem e não são sensíveis a maiúsculas de minúsculas.

Para obter mais informações, na lista padrão de valores de sinalizador de usuário com suporte pelo SDS, consulte Lista padrão de valores: Sinalizadores de Usuário.

Exemplo:

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

Regras de correspondência e validação de dados

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

Importante

Por 1EdTech, é responsabilidade do provedor impor a privacidade de dados para quais dados estão disponíveis quando uma solicitação de dados é feita. A Sincronização de Dados Escolares faz uma solicitação de dados ativos com base na hora da solicitação.

Anotações e dicas úteis

  • Os pontos de extremidade sempre vêm após a url https: {server_URL}/ims/oneroster/v1p1.

  • Todos os pontos de extremidade devem dar suporte à paginação, ou seja, parâmetros de limite e deslocamento (ex: limit=10&offset=5000).

  • Os pontos de extremidade têm requisitos no suporte ao parâmetro de filtro para permitir a filtragem por status ou habilitar a sincronização delta.

  • Os clientes sabem como habilitar a opção "Está Ativo" ou como permitir apenas que os dados ativos estejam disponíveis para a conexão que deve ser usada pela Sincronização de Dados Escolares. Isso garante que apenas dados ativos para o Ano Letivo ativo e a sessão sejam fornecidos à medida que o ano letivo progride.

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

  • Os provedores devem optar por implementar o esquema de autenticação OAuth1(a) ou OAuth 2.0 (concessão de credenciais do cliente), preferencial OAuth 2.0.

  • Durante o desenvolvimento, você pode verificar seus pontos de extremidade com nossa coleção Postman.

  • Se o protocolo de autenticação com suporte for "OAuth 2" – tipo de concessão de credenciais do cliente, o SDS enviará as credenciais no Cabeçalho "Autorização". O SDS não dá suporte ao envio das credenciais no corpo da solicitação.

Testando suas APIs do OneRoster

Usando a coleção Postman

O Postman é uma ferramenta conhecida para executar e gerenciar APIs REST. Criamos a coleção Postman da API do OneRoster para invocar e testar as APIs OneRoster necessárias 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 retornados.

Testar com a engenharia do SDS em um ambiente de área restrita

Crie um ambiente de área restrita para suas APIs do OneRoster e compartilhe as credenciais com o engenheiro do SDS designado. Juntos, executamos um conjunto mais profundo de testes para garantir que a integração seja bem-sucedida.

Configurar para validar a solução

Quando todos os testes tiverem sido bem-sucedidos, o nome do sistema é adicionado à lista de provedores OneRoster no SDS, mas visível apenas para locatários voados para perfis de provedores denotados como sendo o modo 'InPilot' (não disponível publicamente). Em seguida, você integrará o SDS configurando a Ingestão de Dados com a API do OneRoster em seu locatário de teste do Microsoft 365 para sincronizar dados dos pontos de extremidade do OneRoster de área restrita e garantir que as execuções sejam concluídas sem erros. Se você vir erros ou avisos e precisar de ajuda após sua auto-investigação, entre em contato com o engenheiro do SDS designado.

Piloto do cliente

Depois que o teste for concluído com êxito, é hora de começar a pilotar a solução com os clientes. O nome do sistema ficará visível na lista de provedores OneRoster® no SDS para aqueles "voados" para ver também provedores que são o modo "InPilot", tendo concordado em pilotar a integração. A equipe do SDS e a equipe de provedores do OneRoster trabalharão juntas para identificar os clientes piloto apropriados e agendar um tempo para implantar o SDS. Colaboraremos de perto com os clientes para garantir que as execuções de fluxo de entrada sejam bem-sucedidas e validem os resultados em conjunto. Todos os bugs finais identificados devem ser resolvidos antes de disponibilizar a solução publicamente para todos os clientes de educação Office 365.

Ir a público

Depois que dois clientes concluirem com êxito suas implantações piloto, o sistema de parceiros estará disponível no SDS como um sistema de origem de provedor do OneRoster certificado. O SDS exibirá o nome do provedor para locatários quando estiver configurando a Ingestão de Dados com a API do OneRoster. A equipe do SDS também documentará o sistema de parceiros em nossa página de visão geral do provedor de API do OneRoster em nossos documentos online do SDS.

A equipe do SDS precisará:

  • Versão mínima do software
  • Pré-requisitos de configuração
  • Como obter iD do cliente, segredo do cliente e URLs
  • Quaisquer outras instruções específicas
  • Quem entrar em contato para obter ajuda

A equipe do SDS também coordenará com sua equipe para promover a integração de forma mais ampla por meio de vários canais de marketing.