Gegevensexportservice

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online)

De Gegevensexport-service is een invoegtoepassing die beschikbaar wordt gesteld als een Microsoft Dynamics 365 (online)-oplossing. Deze service voegt de mogelijkheid toe om Dynamics 365 (online)-gegevens te repliceren naar een Microsoft Azure SQL-database in een Microsoft Azure-abonnement dat eigendom is van de gebruiker. De ondersteunde doelbestemmingen zijn Microsoft Azure SQL Database en Microsoft Azure SQL Server op virtuele Microsoft Azure-machines. Met Gegevensexport worden het volledige Dynamics 365-schema en de gegevens intelligent gesynchroniseerd met het Microsoft Dynamics 365 (online)-systeem. Daarna worden wijzigingen continu gesynchroniseerd (deltawijzigingen).

De Gegevensexport-service biedt een interface waarmee u de configuratie en het doorlopende beheer van deze service kunt managen vanuit Dynamics 365 (online). Zie voor meer informatie TechNet: Gegevensexport. In dit onderwerp worden de bijbehorende programmatische interface en problemen voor deze service uitgelegd.

Vereisten voor het gebruik van de Gegevensexport-service

Omdat deze service toegang tot een externe Microsoft Azure SQL-database vereist vanuit Dynamics 365 (online), moet aan een aantal vereisten worden voldaan voordat u toegang krijgt tot deze service. De volgende vereisten worden in meer detail uitgelegd vanuit het perspectief van een beheerder in de sectie TechNet: Vereisten voor het gebruik van de Gegevensexport-service.

Uw Dynamics 365 (online)-service moet als volgt zijn geconfigureerd:

• U moet Update voor Microsoft Dynamics 365 (online) - december 2016 of een hoger exemplaar met de oorspronkelijke of volledige gegevenskopie hebben. Zie voor meer informatie Een exemplaar kopiëren.

• Voor de te exporteren entiteiten is het bijhouden van wijzigingen ingeschakeld. Zie Tracering gebruiken om gegevens te synchroniseren met externe systemen voor meer informatie.

• De code wordt uitgevoerd in de context van een gebruiker met de beveiligingsrol Systeembeheerder.

Notitie

Houd er rekening mee dat programmatische toegang tot deze service niet vereist dat de bijbehorende beheerde oplossing voor gegevensexport moet zijn geïnstalleerd.

De doeldatabase (Azure SQL Database) moet als volgt zijn geconfigureerd:

• Het abonnement moet het gegevensvolume ondersteunen dat vanuit uw Dynamics 365-exemplaar wordt gerepliceerd.

• De firewallinstellingen moet toegang vanaf het IP-adres van uw Gegevensexport-service toestaan. Zie voor meer informatie het onderwerp Configure an Azure SQL Database server-level firewall rule using the Azure Portal.

• Het wordt aanbevolen om de optie "Allow access to Azure services" (Toegang tot Azure-services toestaan) in te schakelen.

• De databasegebruiker die wordt opgegeven in de Gegevensexport-verbindingsreeks, moet de juiste machtigingen hebben voor maken (create) en wijzigen (alter) in de doeldatabase. Neem tenminste de machtigingen CRTB, CRTY, CRVW, CRPR en ALUS op. Zie voor meer informatie Permissions (Database Engine).

• Minstens één gebruiker heeft uitgebreide machtigingen voor het schema. U maakt een dergelijke, nieuwe gebruiker met het volgende script.

USE MASTER;
CREATE LOGIN NewUser WITH PASSWORD='newpassword';

USE DESTINATIONDATABASE;
CREATE USER NewUser FOR LOGIN NewUser
GRANT CREATE TABLE, CREATE TYPE, CREATE VIEW, CREATE PROCEDURE, ALTER ANY USER to NewUser
GRANT ALTER, REFERENCES, INSERT, DELETE, UPDATE, SELECT, EXECUTE ON SCHEMA::dbo TO NewUser

Voor online oplossingen en services biedt Azure een Sleutelkluis-service, waarin cryptografische sleutels, wachtwoorden en andere secrets kunnen worden opgeslagen. Om Azure Sleutelkluis te gebruiken moet deze klantservice worden geconfigureerd zodat de machtiging wordt verleend aan Dynamics 365 Gegevensexportservice, die wordt gebruikt om de SQL Azure-verbindingsreeks op te slaan. Als u deze configuratie met een Powershell-script wilt uitvoeren raadpleegt u TechNet: Het instellen van Azure Sleutelkluis. U kunt deze service eventueel ook beheren via de bijbehorende REST-API. Zie hiervoor Key Vault Management.

Het wordt ook aanbevolen om het domein https://discovery.crmreplication.azure.net/ toe te voegen aan de lijst met vertrouwde websites in uw browser, zodat deze site pop-ups kan weergeven.

Programmeren voor de Gegevensexport-service

De Gegevensexport-service stelt een op REST-gebaseerd API beschikbaar, die is verdeeld in twee groepen: een reeks Metadata-bewerkingen voor het onderzoeken van de organisatiestructuur, relaties en verbindingsgegevens voor Dynamics 365; en een reeks Profiles-bewerkingen voor het configureren en beheren van de gegevensreplicatie. Deze API wordt volledig gedefinieerd en gedocumenteerd op volgende Swagger-URL's:

Swagger-eindpunt	Beschrijving
https://discovery.crmreplication.azure.net/swagger/docs/2016-01-01	JSON-definitie van de API voor de Gegevensexport-service, voor gebruik door ontwikkelaarhulpprogramma's en dynamische processen
https://discovery.crmreplication.azure.net/swagger/ui/index#	De gebruikersvriendelijke versie van deze API voor ontwikkelaarreferentie

Snelle naslag voor de API

Voor het gemak worden deze interfaces samengevat in de onderstaande tabellen.

Bewerkingen met metagegevens (https://discovery.crmreplication.azure.net/crm/exporter/metadata/)

Resource	Methoden	Beschrijving
organizations	GET	Organisatiegegevens ophalen voor alle organisaties waar de huidige gebruiker deel van uitmaakt
discover	GET	Organisatiegegevens ophalen voor de opgegeven organisatie
connector	GET	Connectorgegevens ophalen voor de opgegeven organisatie
entities	GET	Alle uitvoerbare openbare entiteiten ophalen voor de opgegeven organisatie
relationships	GET	Alle uitvoerbare relaties ophalen voor de opgegeven organisatie
hasorgacceptedprivacyterms	GET	Controleren of de gekoppelde organisatie de privacyvoorwaarden heeft geaccepteerd
acceptprivacyterms	POST	De opgegeven organisatie accepteren voor gegevenstoegang

Bewerkingen met profielen ([Organization-URI]/crm/exporter/)

Resource	Methoden	Beschrijving
profiles	GET, POST	Alle profielen voor opgegeven organisatie ophalen, een nieuw exportprofiel maken
profiles/{id}	GET, PUT, DELETE	Een specifiek profiel ophalen, bijwerken of verwijderen
profiles/{id}/activate	POST	Een profiel activeren, waardoor replicatie van de gekoppelde metagegeven en de gegevens wordt gestart
profiles/{id}/activatemetadata	POST	Profiel activeren, alleen voor replicatie van metagegevens
profiles/{id}/activatedata	POST	Profiel activeren, alleen voor replicatie van gegevens
profiles/{id}/deactivate	POST	Een profiel deactiveren
profiles/{id}/test	GET	Testbewerkingen uitvoeren op een bestaand profiel
profiles/validate	POST	Testbewerkingen uitvoeren op een profielbeschrijving voordat het profiel wordt gemaakt
profiles/{id}/failures	GET	De verbindingstekenreeks ophalen voor een blob die foutdetails voor een specifiek profiel bevat

Toegang

Omdat alleen systeembeheerders van Dynamics 365 gemachtigd zijn om bewerkingen voor gegevensexport uit te voeren, dwingen deze API's verificatie van de aanroepende partij af door middel van beveiligingstokens van Azure Active Directory (AAD). In het volgende codefragment wordt getoond hoe een dergelijke token wordt gegenereerd voor een webtoepassing, door gebruik van de naam en het wachtwoord van de beheerder. Vervang de waarden voor AppId, crmAdminUser en crmAdminPassword door de betreffende waarden voor uw service. U kunt deze methode gebruiken voor de fasen ontwikkeling en testen. Voor de productiefase moeten echter beter beveiligde manieren worden gebruikt, zoals bijvoorbeeld de Azure Sleutelkluis.

//Reference Azure AD authentication Library (ADAL)  
using Microsoft.IdentityModel.Clients.ActiveDirectory;
   . . .
    string yourAppClientID = "[app-associated-GUID]";   //Your AAD-registered AppId 
    string crmAdminUser = "admin1@contoso.com";  //Your CRM administrator user name
    string crmAdminPassword = "Admin1Password";  //Your CRM administrator password; 
    //For interactive applications, there are overloads of AcquireTokenAsync() which prompt for password. 
    var authParam = AuthenticationParameters.CreateFromResourceUrlAsync(new 
        Uri("https://discovery.crmreplication.azure.net/crm/exporter/aad/challenge")).Result;
    AuthenticationContext authContext = new AuthenticationContext(authParam.Authority, false);
    string token = authContext.AcquireTokenAsync(authParam.Resource, yourAppClientID, 
        new UserCredential(crmAdminUser, crmAdminPassword)).Result.AccessToken;

Instructies voor het verkrijgen van een AppId vindt u in Authorize access to web applications using OAuth 2.0 and Azure Active Directory. Meer informatie over gebruikersbeveiliging in Azure vindt u in Authentication Scenarios for Azure AD.

Foutafhandeling en foutverwerking

Wanneer een profiel eenmaal correct is geconfigureerd, is het synchronisatieproces meestal zeer betrouwbaar. Echter, als het synchroniseren van een record mislukt, wordt de volgende foutverwerking toegepast:

1. Na het geconfigureerde interval voor nieuwe poging wordt een andere poging ondernomen om de record te synchroniseren. Dit wordt herhaald tot het geconfigureerde maximale aantal pogingen is uitgevoerd.

2. De record wordt gemarkeerd als verwerkt.

3. Een overeenkomende mislukte recordvermelding wordt naar het foutlogboek weggeschreven.

4. De volgende record wordt verwerkt.

Omdat de record is gemarkeerd als verwerkt, wordt er geen toekomstige poging ondernomen om de record te synchroniseren totdat de waarde of het schema worden gewijzigd. (Bij het terugschrijven van identieke waarden naar een entiteitsexemplaar wordt dit ook als gewijzigd gemarkeerd.)

De vermeldingen in het foutlogboek zijn alleen-schrijven. Toekomstige geslaagde of mislukte pogingen tijdens synchronisatie van dezelfde record resulteren niet in de wijziging van eerdere vermeldingen voor deze record. Zo blijft bijvoorbeeld een foutvermelding in het foutlogboek staan zelfs nadat de record tijdens een latere synchronisatiecyclus met succes is gesynchroniseerd.

Waarschuwing

Deze logica bij de foutverwerking zal in toekomstige versies van deze service worden gewijzigd.

Deze foutvermeldingen kunnen worden opgehaald via de aanvraag De foutdetails voor een specifiek profiel ophalen. De respons retourneert een URI naar een Azure-blob die de foutgegevens bevat. Elke regel bevat de volgende door komma's gescheiden velden (nieuwe regels toegevoegd voor de duidelijkheid):

Entity: <entity-name>, 
RecordId: <”N/A” | guid>, 
NotificationTime: <datetime>, 
ChangeType: <sync-type>,
FailureReason: <description>

Bijvoorbeeld:

Entity: lead, 
RecordId: N/A, NotificationTime: , ChangeType: Trigger Initial Export, FailureReason: There is already an object named 'hatest201_lead' in the database.
Entity: account, RecordId: b2a19cdd-88df-e311-b8e5-6c3be5a8b200, NotificationTime: 8/31/2016 6:50:38 PM, ChangeType: New, FailureReason: Invalid object name 'dbo.hatest201_account'.

Zie ook

Uw gegevens beheren in Microsoft Dynamics 365
Gegevens importeren

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht