Benutzerdefinierte APIs erstellen und verwenden

Verwenden Sie benutzerdefinierte APIs, um Ihre eigenen APIs in Dataverse zu erstellen. Sie können einen oder mehrere Vorgänge in einer benutzerdefinierten API konsolidieren, die Sie und andere Entwickler in ihrem Code oder von Power Automate aus aufrufen können. Der Microsoft Dataverse-Connector ermöglicht das Aufrufen von Aktionen in Power Automate.

Sie können benutzerdefinierte APIs als Geschäftsereignisse verwenden, um das Erstellen neuer Integrationsfunktionen zu ermöglichen, z. B. das Verfügbarmachen eines neuen Typs von Auslöser im Microsoft Dataverse-Connector. Weitere Informationen: Microsoft Dataverse-Geschäftsereignisse

Benutzerdefinierte APIs sind eine Alternative zu benutzerdefinierten Prozessaktionen. Benutzerdefinierte Prozessaktionen bieten eine Möglichkeit ohne Code, benutzerdefinierte Nachrichten einzuschließen, weisen jedoch einige Einschränkungen für Entwickler auf. Benutzerdefinierte APIs bieten Funktionen speziell für Entwickler, um ihre Logik im Code mit mehr Optionen zu definieren. Einen vollständigen Vergleich von benutzerdefinierten Prozessaktionen und benutzerdefinierten APIs finden Sie unter Vergleich einer benutzerdefinierten Prozessaktion mit einer benutzerdefinierten API.

Benutzerdefinierte API erstellen

Eine benutzerdefinierte API kann Logik enthalten, die mit einem Plug-In implementiert ist. Wenn Sie Microsoft Dataverse-Geschäftsereignisse verwenden, können Sie eine benutzerdefinierte API ohne Plug-In erstellen, um Daten zu einem Ereignis weiterzugeben, auf das andere Abonnenten reagieren.

In anderen Fällen kombinieren Sie jedoch eine benutzerdefinierte API mit einem Plug-In, um einen Vorgang zu definieren, an den Dataverse delegiert wird, um das Ergebnis zu berechnen und zurückzugeben.

Es gibt verschiedene Möglichkeiten, eine benutzerdefinierte API zu erstellen:

Methodenlink	Leistung
Plug-in Registration Tool	Ein benutzerfreundliches GUI-Tool, das in Tools integriert ist, die zur Entwicklung von Plug-Ins verwendet werden.
Power Apps	Verwendung von Formularen zur Eingabe von Daten. Sie müssen kein separates Tool installieren, Sie müssen für jeden Teil der benutzerdefinierten API einen separaten Datensatz erstellen.
Mit Code	Nachdem Sie das Datenmodell verstanden haben, können Sie mit Postman schnell eine benutzerdefinierte API erstellen. Oder Sie können Ihre eigene Umgebung aufbauen, um eine benutzerdefinierte API zu erstellen.
Mit Lösungsdateien	Wenn Sie Tools des Application Lifecycle Management (ALM) verwenden, können Sie benutzerdefinierte API-Definitionen mit XML-Dateien in einer Lösung erstellen oder ändern, die in Ihrem Quellcode-Repository enthalten ist. Die benutzerdefinierte API wird erstellt, wenn Sie die aus Ihrem Quellcode generierte Lösung importieren.

Hinweis

Obwohl Daten der benutzerdefinierten API in Tabellen gespeichert werden, unterstützen wir nicht das Erstellen einer modellbasierten App für diese Tabellen.

Dies sind einige der Tools, die von der Community erstellt und unterstützt werden, um mit der benutzerdefinierten API zu arbeiten:

• Benutzerdefinierter Dataverse-API-Manager
• Benutzerdefinierter API-Tester
• Umwandlung benutzerdefinierter Aktionen in benutzerdefinierte APIs

Von der Community erstellte Tools werden von Microsoft nicht unterstützt. Wenn Sie Fragen oder Probleme mit Community-Tools haben, wenden Sie sich an den Herausgeber des Tools.

Custom-API-Anpassung

Beim Erstellen einer benutzerdefinierten API und den zugehörigen Anfrageparametern und Antworteigenschaften ist es wichtig zu verstehen, dass diese API-Definitionen standardmäßig angepasst werden können. Die Anpassungsfähigkeit erlaubt es Ihnen, diese Elemente in Ihrer nicht verwalteten Lösung zu iterieren und zu ändern.

Wichtig

Wenn Sie Ihre Lösung ausliefern oder bereitstellen, sollten Sie eine verwaltete Lösung verwenden und wir empfehlen, dass Sie die verwaltete Eigenschaft Ist anpassbar für diese Komponenten immer auf false festlegen. Dadurch wird verhindert, dass Personen, die Ihre verwaltete Lösung verwenden, diese Komponenten Ihrer Lösung ändern oder löschen können. Solche Änderungen könnten Code zerstören, der für die ursprüngliche Definition der benutzerdefinierten API geschrieben wurde.

Legen Sie Ist anpassbar auf false fest

Sie können die verwaltete Eigenschaft Ist anpassbar aus der Lösung in Power Apps einstellen.

Sie müssen diese Eigenschaft für jede benutzerdefinierte API, jeden Anforderungsparameter und jede Antworteigenschaft einzeln festlegen.

Weitere Informationen Verwaltete Eigenschaften

Fügen Sie weitere Anforderungsparameter und Antworteigenschaften hinzu

Auch wenn Sie die verwaltete Eigenschaft Ist anpassbar dieser Komponenten auf false festgelegt haben, können neue Anfrageparameter und Antworteigenschaften zu Ihrer benutzerdefinierten API hinzugefügt werden. Diese Anforderungsparameter können jedoch nicht erforderlich gemacht werden. Wenn Sie benutzerdefinierte Verarbeitungsschritte auf Ihrer benutzerdefinierten API zulassen möchten, können sie andere Plug-Ins verwenden, die für die von Ihrer benutzerdefinierten API erstellte Nachricht registriert sind. Da benutzerdefinierte Anforderungsparameter nur optional sein können, kann das Plug-In, das Sie für den Hauptbetrieb der benutzerdefinierten API bereitstellen, diese ignorieren und ist nicht dafür verantwortlich, benutzerdefinierte Anforderungsparameter zu verwenden oder benutzerdefinierte Antworteigenschaften festzulegen.

Custom-API-Tabellen/-Entitäten

Siehe CustomAPI-Tabellen für Informationen zu den Tabellen und Spaltenwerten, die beim Erstellen benutzerdefinierter APIs verwendet werden sollen.

Benutzerdefinierten Verarbeitungsschritttyp auswählen

Die folgende Tabelle beschreibt, welchen Benutzerdefinierter Verarbeitungsschritttyp (AllowedCustomProcessingStepType) der benutzerdefinierten API Sie verwenden sollten.

Option	Verwenden des s
Keine	Wenn das für diese benutzerdefinierte API mithilfe von CustomAPI.PluginTypeId festgelegte Plug-In die einzige Logik ist, die auftritt, wenn dieser Vorgang ausgeführt wird. Sie gestatten keinen anderen Entwickelnden, weitere Schritte zu registrieren, die andere Logik auslösen, das Verhalten dieses Vorgangs ändern oder den Vorgang abbrechen können. Verwenden Sie diese Option, wenn die benutzerdefinierte API einige Funktionen bereitstellt, die nicht anpassbar sein sollten.
Nur asynchron	Wenn Sie zulassen möchten, dass andere Entwickler erkennen, wann dieser Vorgang auftritt, Sie aber nicht möchten, dass sie den Vorgang abbrechen oder das Verhalten des Vorgangs anpassen können. Andere Entwickler können asynchrone Schritte registrieren, um zu erkennen, dass dieser Vorgang aufgetreten ist, und darauf reagieren, nachdem er abgeschlossen ist. Diese Option wird empfohlen, wenn Sie das Geschäftsereignismuster verwenden. Ein Geschäftsereignis erstellt einen Auslöser in Power Automate, den Sie verwenden können, wenn dieses Ereignis eintritt. Weitere Informationen: Microsoft Dataverse-Geschäftsereignisse
Synchron und asynchron	Wenn Sie anderen Entwicklern die Möglichkeit geben möchten, das Verhalten des Vorgangs zu ändern und ihn sogar abzubrechen, wenn es ihre Geschäftslogik vorschreibt. Wenn der Vorgang erfolgreich ist, können andere Entwickler dieses Ereignis ebenfalls erkennen und Logik für die asynchrone Ausführung hinzufügen. Die meisten Dataverse Nachrichten ermöglichen eine Erweiterung auf diese Weise. Verwenden Sie diese Option, wenn Ihre Nachricht einen Geschäftsprozess darstellt, der anpassbar sein sollte.

Wählen Sie einen Bindungstyp aus

Bindung ist ein OData-Konzept, das eine Operation einer bestimmten Tabelle zuordnet. Die folgende Tabelle beschreibt die benutzerdefinierte API den Bindungstyp (BindingType), den du verwenden solltest.

Option	Verwenden des s
Global	Wenn der Vorgang nicht auf eine bestimmte Tabelle zutrifft.
Entität	Wenn die Operation einen einzelnen Datensatz einer bestimmten Tabelle als Parameter akzeptiert.
EntityCollection	Wenn der Vorgang Änderungen an einer bestimmten Tabelle anwendet oder eine Auflistung einer bestimmten Tabelle zurückgibt.

Das Auswählen von Entität oder EntityCollection erfordert, dass Sie den vollqualifizierten Namen der Funktion oder Aktion verwenden, wenn Sie die Web-API verwenden. Vollqualifizierter Name lautet Microsoft.Dynamics.CRM.<UniqueName of the custom API>.

Wenn Sie Entität auswählen, wird ein Anforderungsparameter namens Target mit dem Typ EntityReference automatisch erstellt. Sie brauchen sie nicht zu erstellen. Dieser Wert wird an alle Plug-Ins weitergegeben, die für diese Nachricht registriert sind.

Wenn Sie EntityCollection auswählen, ist kein Parameter oder keine Antworteigenschaft enthalten, die die Entitätssammlung darstellt. Durch das Festlegen dieser Bindung wird lediglich die Anforderung hinzugefügt, dass die Operation bei Verwendung der Web-API an das Entityset angehängt aufgerufen wird.

Hinweis

Diese Bindungstypen können Sie beim Erstellen Ihrer benutzerdefinierten API verwenden, aber es ist nicht erforderlich, dass Sie eine Bindung an eine Entität oder Entitätssammlung herstellen. Sie können alle Ihre benutzerdefinierten APIs als Global zusammenstellen und fügen die Anforderungsparameter oder Antworteigenschaften hinzu, die Sie benötigen, um die gleiche Funktionalität wie eine gebundene Funktion oder Aktion zu erreichen.

Weitere Informationen:

• An eine Tabelle gebundene Aktionen
• An eine Tabellensammlung gebundene Aktionen
• Gebundene Funktionen

Wann eine Funktion erstellen

Die Eigenschaft Is Function der benutzerdefinierten API steuert, ob die benutzerdefinierte API eine Funktion oder Aktion ist. In OData ist eine Funktion ein Vorgang, der über die HTTP-Anforderung GET aufgerufen wird, die Daten zurückgibt, ohne Änderungen vorzunehmen. Mit einer GET-Anforderung werden alle Parameter als Parameter in der URL übergeben, wenn die Funktion aufgerufen wird.

Sie können GET-Anforderungen einfacher nur über Ihren Browser testen, aber die Länge der URL, die gesendet werden kann, ist auf 32 KB (32.768 Zeichen) begrenzt. Wenn Ihre benutzerdefinierte API viele komplexe Anforderungsparameter hat, die dazu führen können, dass die Länge der URL zu lang wird, ist es akzeptabel, eine Aktion zu erstellen, die denselben Vorgang ausführt und alle Parameterdaten im Hauptteil mit POST-Anforderung übergibt.

Hinweis

• Funktionen müssen einige Daten zurückgeben. Sie müssen mindestens eine Antworteigenschaft einschließen, damit die benutzerdefinierte API gültig ist.
  • Eine Funktion, die keine Antworteigenschaft enthält, wird nicht im $metadata-Dienstdokument der Web-API angezeigt.
  • Wenn Sie versuchen, eine ungültige Funktion zu verwenden, erhalten Sie einen 404 Not found-Fehler ähnlich wie dieser:
    {"error":{"code":"0x8006088a","message":"Resource not found for the segment 'your_function_name'."}}
• Eine Funktion ist nicht zulässig, wenn die Für Workflow aktiviert Option ausgewählt ist. Siehe Verwenden Sie eine benutzerdefinierte API in einem Workflow
• Derzeit der Microsoft Dataverse Connector ermöglicht nur das Ausführen von Aktionen. Wenn Sie den Vorgang mit Power Automate ausführen müssen, sollten Sie Ihre benutzerdefinierte API als Aktion erstellen.

Weitere Informationen: Verwenden von Web-API-Funktionen

Wann Sie Ihre benutzerdefinierte API privat machen sollten

Standardmäßig steht jede benutzerdefinierte API, die Sie erstellen, anderen Entwicklern zum Entdecken und Verwenden zur Verfügung. Als Herausgeber der benutzerdefinierten API sind Sie verpflichtet, die von Ihnen erstellten öffentlichen APIs zu warten. Sie sollten Ihre API nicht entfernen oder Änderungen vornehmen, die andere Anwender beeinträchtigen.

Wenn Sie nicht bereit sind, andere Entwickler mit Ihrer benutzerdefinierten API zu unterstützen, sollten Sie die Eigenschaft Is Private (IsPrivate) der benutzerdefinierten API auf „true“ setzen, bevor Sie die verwaltete Lösung versenden, die Ihre benutzerdefinierte API enthält.

Die Is Private-Eigenschaft blockiert das Erscheinen der benutzerdefinierten API im $metadata-Dienstdokument und verhindert Dataverse-Codegenerierungstools vom Erstellen von Klassen, um die Nachrichten für Ihre benutzerdefinierte API zu verwenden.

Das Festlegen dieser Eigenschaft bedeutet nicht, dass andere Entwickler Ihre Nachricht nicht verwenden können, wenn sie davon wissen und eine Anforderung zur Verwendung verfassen können. Das Festlegen der Is Private-Eigenschaft ist eine Möglichkeit, anzugeben, dass Sie andere Entwickler, die Ihre Nachricht verwenden, nicht unterstützen.

Möglicherweise möchten Sie eine benutzerdefinierte API privat halten, bis Sie sicher sind, dass Sie sie nicht entfernen oder eine bahnbrechende Änderung einführen müssen.

Sie können Ist privat in Ihrer Entwicklungsumgebung auf false setzen, damit Sie die Ausgabe im $metadata-Dienstdokument sehen oder Klassen für Ihre eigene Verwendung generieren können. Bevor Sie jedoch die benutzerdefinierte API in Ihrer verwalteten Lösung versenden, sollten Sie Ist privat auf „true“ festlegen.

Weitere Informationen:

• CSDL-$Metadatendokument
• Generieren von Klassen mit früher Bindung für das SDK für .NET
• Private Nachrichten

Sichern Sie Ihre benutzerdefinierte API mit einem Recht

Legen Sie die benutzerdefinierte API-Eigenschaft Berechtigungsname ausführen (ExecutePrivilegeName) auf den Namen der Berechtigung, um sie erforderlich zu machen. Derzeit gibt es keine unterstützte Möglichkeit für Entwickler außerhalb von Microsoft, neue Berechtigungen zu erstellen. Es kann jedoch eine vorhandene Berechtigung verwendet werden. Weitere Informationen: F: Kann ich eine neue Berechtigung für meine benutzerdefinierte API erstellen?

Verwenden Sie ein Plug-In, um Logik in Ihre benutzerdefinierte API einzufügen

Wenn Sie die benutzerdefinierte API nicht auf Plugin-Typ (PluginTypeId) festlegen, um die Hauptvorgangslogik anzugeben, können Sie weiterhin die benutzerdefinierte API aufrufen.

Sie können sich dafür entscheiden, keine Logik in das Plug-In aufzunehmen, weil Sie die benutzerdefinierte API als Geschäftsereignis verwenden. Weitere Informationen: Microsoft Dataverse-Geschäftsereignisse.

Möglicherweise möchten Sie kein Plug-In als Testschritt hinzufügen. Ohne ein Plug-In geben alle Ausgabeparameterwerte die Standardwerte für den Typ zurück, da kein Code zum Festlegen vorhanden ist. Andernfalls finden Sie weitere Informationen unter Plug-in für Ihre benutzerdefinierte API schreiben

Hinweis

Sie können keine Konfigurationsdaten an das für die Hauptbetriebslogik angegebene Plug-In übergeben. Hierfür gibt es eine Problemumgehung.

Eine benutzerdefinierte API in einem Workflow verwenden

Legen Sie die benutzerdefinierte API Für Workflow aktiviert (WorkflowSdkStepEnabled) auf „true“, wenn Sie das Aufrufen einer benutzerdefinierten API als Workflow-Aktion aktivieren müssen. Bei Auswahl dieser Option gelten jedoch die folgenden Einschränkungen, damit die benutzerdefinierte API im Workflow-Designer aufgerufen werden kann:

• Die benutzerdefinierte API kann keine Funktion sein. Is Function muss „false“ sein.

• Die benutzerdefinierte API darf nur Anforderungsparameter- oder Antworteigenschaftstypen haben, die der Workflow unterstützt:

  • Boolesch
  • DateTime
  • Decimal
  • EntityReference
    • „EntityReference“ kann nur verwendet werden, wenn die benutzerdefinierte API an eine Entität gebunden ist.
  • Float
  • Ganzzahl
  • Money
  • Auswahlliste
  • Zeichenfolge
  • GUID

  Die folgenden Anforderungsparameter- oder Antworteigenschaftstypen können nicht verwendet werden:

  • Entity
  • EntityCollection
  • StringArray

Benutzerdefinierte APIs aufrufen

Eine benutzerdefinierte API erstellt eine neue Nachricht, die wie jeder andere Vorgang über die Web-API oder das Dataverse-SDK für .NET aufgerufen werden kann.

Benutzerdefinierte APIs von der Web-API aus aufrufen

Während des Tests können Sie Ihre API mithilfe von PostMan aufrufen. Führen Sie die unter Eine Postman-Umgebung einrichten beschriebenen Schritte aus, um eine PostMan-Umgebung einzurichten, die das benötigte Zugriffstoken generiert. Führen Sie dann die unter Web-API-Aktionen verwenden beschriebenen Schritte aus, wenn Ihre API eine Aktion ist. Wenn es sich um eine Funktion handelt, folgen Sie den Schritten unter Web-API-Funktionen verwenden.

Siehe folgende Beispiele:

Ungebundene Aktion

Diese Aktion lautet myapi_CustomUnboundAPI. Es hat einen einzelnen String-Anforderungsparameter namens InputParameter:

POST [Organization URI]/api/data/v9.1/myapi_CustomUnboundAPI
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
  "InputParameter": "Value"
}

An Tabelle gebundene Funktion

Diese Funktion namens myapi_CustomBoundAPI ist an die Kontentabelle gebunden:

GET [Organization URI]/api/v9.1/accounts(ed5d4e42-850c-45b7-8b38-2677545107cc)/Microsoft.Dynamics.CRM.myapi_CustomBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

An Tabellensammlung gebundene Funktion

Diese Funktion namens myapi_CustomEntityCollectionBoundAPI ist an die Kontentabellensammlung gebunden:

GET [Organization URI]/api/v9.1/accounts/Microsoft.Dynamics.CRM.myapi_CustomEntityCollectionBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Weitere Informationen:

• Nutzen von Web-API-Aktionen
• Nutzen von Web-API-Funktionen

Aufrufen von angepassten APIs aus dem SDK für .NET

Sie können wählen, ob Sie früh- oder spät-gebundenen Code verwenden, um Ihre angepasste API aufzurufen. Verwenden Sie das pac modelbuilder build-Tool zum Generieren von Hilfsanforderungs- und Antwortklassen, um die Anforderungsparameter und Antworteigenschaften Ihrer benutzerdefinierten API bereitzustellen. Erfahren Sie mehr über das Generieren von Klassen mit früher Bindung für das SDK für .NET.

Für spät gebundenen Code oder eine benutzerdefinierte API, die Sie als privat gekennzeichnet haben, erstellen Sie eine OrganizationRequest mit dem eindeutigen Namen Ihrer benutzerdefinierten API und fügen Sie Parameter mit Namen hinzu, die mit den eindeutigen Namen der Anforderungseigenschaften übereinstimmen.

An Entitäten gebundene benutzerdefinierte APIs haben eine implizite Anforderungseigenschaft namens Target, die auf ein EntityReference des Datensatzes festgelegt werden sollte, für den die API aufgerufen werden soll.

Sie können über die Parameter der zurückgegebenen Antwort auf die Antwort-Eigenschaften zugreifen.

In diesem Beispiel wird eine benutzerdefinierte API mit dem Namen myapi_EscalateCase an die Vorfallstabelle gebunden, um einen Datensatz als Target-Parameter zusammen mit einem anderen Optionssatz-Wertanforderungsparameter namens Priority zu akzeptieren. Es hat eine EntityReference-Antworteigenschaft namens AssignedTo.

var req = new OrganizationRequest("myapi_EscalateCase")
{
  ["Target"] = new EntityReference("incident", guid),
  ["Priority"] = new OptionSetValue(1)
};

var resp = svc.Execute(req);

var newOwner = (EntityReference) resp["AssignedTo"];

Weitere Informationen: Nachrichten mit dem SDK für .NET verwenden.

Rufen Sie die benutzerdefinierte API als Hintergrundvorgang auf

Die mit einem Hintergrundvorgang auszuführende Logik muss als benutzerdefinierte API definiert werden. Weitere Informationen: Hintergrundvorgänge (Vorschauversion)

Ein Plug-In für Ihre benutzerdefinierte API schreiben

Das Schreiben eines Plug-Ins zum Implementieren des Hauptvorgangs für Ihre benutzerdefinierte API unterscheidet sich nicht vom Schreiben eines anderen Plug-Ins, außer dass Sie das Plug-In-Registrierungstool nicht zum Festlegen eines bestimmten Schritts verwenden und Sie können keine Konfigurationsdaten angeben, die an das Plug-In übergeben werden.

Sie müssen die folgenden Informationen kennen:

• Der Name der Nachricht
• Die Namen und Typen der Anforderungsparameter und Antworteigenschaften.

Die Anforderungsparameterwerte sind in den InputParameters enthalten.

Sie müssen die Werte für die Antworteigenschaften in den OutputParameters festlegen.

Der folgende Code ist ein einfaches Plug-In, das die Zeichen in StringParameter umkehrt und das Ergebnis als StringProperty zurückgibt.

using System;
using System.Linq;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

namespace CustomAPIExamples
{
    public class Sample_CustomAPIExample : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            // Obtain the execution context from the service provider.  
            IPluginExecutionContext context = (IPluginExecutionContext)
                serviceProvider.GetService(typeof(IPluginExecutionContext));

            if (context.MessageName.Equals("sample_CustomAPIExample") && context.Stage.Equals(30)) {

                try
                {
                    string input = (string)context.InputParameters["StringParameter"];
                    
                    if (!string.IsNullOrEmpty(input)) {
                        //Simply reversing the characters of the string
                        context.OutputParameters["StringProperty"] = new string(input.Reverse().ToArray());
                    }
                }
                catch (Exception ex)
                {
                    tracingService.Trace("Sample_CustomAPIExample: {0}", ex.ToString());
                    throw new InvalidPluginExecutionException("An error occurred in Sample_CustomAPIExample.", ex);
                }
            }
            else
            {
                tracingService.Trace("Sample_CustomAPIExample plug-in is not associated with the expected message or is not registered for the main operation.");
            }
        }
    }
}

Weitere Informationen zum Schreiben von Plug-Ins finden Sie unter Tutorial: Ein Plug-In schreiben und registrieren. Sie müssen die Assembly registrieren, aber Sie müssen keinen Schritt registrieren. Weitere Informationen: Verwenden Sie ein Plug-In, um Logik in Ihre benutzerdefinierte API einzufügen

Siehe Beispiel Beispiel: Benutzerdefinierte IsSystemAdmin-API

Stellen Sie nach der Registrierung der Assembly sicher, dass Sie die Assembly und alle Typen zu Ihrer Lösung hinzufügen.

Lokalisierbare Label-Werte

Custom-APIs haben einige lokalisierbare Labels. Sie können die Label-Werte anhand der hier dokumentierten Schritte lokalisieren: Übersetzen von lokalisierbarem Text für modellbasierte Apps und Übersetzen von Labels und Display-Strings.

Bei diesem Vorgang wird eine Datei exportiert, die die Werte der Ausgangssprache enthält und für jede aktivierte Sprache eine Spalte enthält. Sie können die Werte dann in Excel bearbeiten. Nachdem Sie den Importvorgang der Übersetzungen abgeschlossen haben, werden die Beschriftungen in Ihre Lösung aufgenommen.

Das folgende Beispiel zeigt das Bearbeiten des Excel-Arbeitsblatts, um japanische Übersetzungen für die englischen Werte hinzuzufügen.

Tipp

Wenn Sie die Lösungsdateien bearbeiten, um Ihre benutzerdefinierten APIs zu erstellen, können Sie die lokalisierten Beschriftungen direkt bereitstellen. Weitere Informationen: Lokalisierte Beschriftungen in der Lösung bereitstellen

Festlegen von lokalisierten Werten

Wenn Sie es vorziehen, lokalisierte Beschriftungen im Code festzulegen, anstatt den oben beschriebenen manuellen Prozess zu verwenden, können Sie die SetLocLabels-Meldung entweder mithilfe der SetLocLabels-Aktion der Web-API oder SetLocLabelsRequest des SDK für .NET verwenden.

Das folgende Beispiel zeigt, wie Sie die Web-API verwenden, um die lokalisierten Labels für die Eigenschaft displayname einer angepassten API festzulegen.

Anforderung:

POST [Organization URI]/api/data/v9.1/SetLocLabels HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json

{
    "EntityMoniker": {
        "@odata.type": "Microsoft.Dynamics.CRM.customapi",
        "customapiid": "86bcd12e-2f30-eb11-a813-000d3a122b89"
    },
    "AttributeName": "displayname",
    "Labels": [
        {
            "Label": "例え",
            "LanguageCode": 1041
        },
        {
            "Label": "Beispiel",
            "LanguageCode": 1031
        },
        {
            "Label": "ejemplo",
            "LanguageCode": 1034
        }
    ]
}

Antwort:

HTTP/1.1 204 No Content

Lokalisierte Werte abrufen

Verwenden Sie zum Abrufen der lokalisierten Beschriftungen die RetrieveLocLabels-Nachricht entweder über die RetrieveLocLabels-Funktion der Web-API oder die RetrieveLocLabelsRequest-Klasse des SDK für .NET.

Das folgende Beispiel zeigt die Verwendung der RetrieveLocLabels-Funktion zum Abrufen der Beschriftungen für die displayname-Eigenschaft einer benutzerdefinierten API mit der customapiid von 88602189-183d-4584-ba4b-8b60f0f5b89f

Anforderung:

GET [Organization URI]/api/data/v9.1/RetrieveLocLabels(EntityMoniker=@p1,AttributeName=@p2,IncludeUnpublished=@p3)?
@p1={'@odata.id':'customapis(88602189-183d-4584-ba4b-8b60f0f5b89f)'}&
@p2='displayname'&
@p3=false HTTP/1.1

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveLocLabelsResponse",
    "Label": {
        "LocalizedLabels": [
            {
                "Label": "Custom API Example",
                "LanguageCode": 1033,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            },
            {
                "Label": "カスタムAPIの例",
                "LanguageCode": 1041,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            }
        ],
        "UserLocalizedLabel": {
            "Label": "Custom API Example",
            "LanguageCode": 1033,
            "IsManaged": null,
            "MetadataId": null,
            "HasChanged": null
        }
    }
}

Häufig gestellte Fragen (Frequently Asked Questions, FAQs)

Im Folgenden finden Sie Fragen, die Sie möglicherweise haben:

F: Kann ich eine neue Berechtigung für meine benutzerdefinierte API erstellen?

A: Während die benutzerdefinierte API eine Eigenschaft Execute Privilege Name (ExecutePrivilegeName) aufweist, gibt es derzeit keine unterstützte Möglichkeit, eine neue Berechtigung nur für diese API zu erstellen. Diese Funktion ist für ein zukünftiges Release geplant. In der Zwischenzeit gibt es zwei Möglichkeiten:

• Sie können einen vorhandenen Privilege.Name-Wert verwenden.
• Sie können eine benutzerdefinierte Entität erstellen und eine der für diese Entität erstellten Berechtigungen verwenden. Erstellen Sie beispielsweise eine Entität mit dem Namen new_myaction und Berechtigungen für CRUD-Vorgänge, die dafür generiert werden. Beispiel: prvCreatenew_myaction. Sie müssen diese benutzerdefinierte Entität in die Lösung aufnehmen, die die benutzerdefinierte API enthält.

F: Kann ich benutzerdefinierte API-Datensätze aktivieren oder deaktivieren?

A: Können Sie nicht. Obwohl diese Datensätze die allgemeinen Spalten Status und Statusgrund haben, die in den meisten Microsoft Dataverse-Tabellen zu finden sind. Das Festlegen der Werte für diese Spalten hat keinen Einfluss auf die Verfügbarkeit der Custom-API, die Anforderungsparameter oder die Antwort-Eigenschaften.

F: Wie kann ich meine privaten Nachrichten verwenden, wenn sie nicht im Web-API-$metadata-Dienstdokument enthalten sind?

A: Ihre privaten Nachrichten funktionieren unabhängig davon, ob sie im Web-API-CSDL-$metadata-Dokument angekündigt werden oder nicht. Während Sie Ihre Lösung entwickeln, können Sie den IsPrivate-Wert auf false festgelegt lassen. Auf diese Weise können Sie auf die $metadata-Liste verweisen und Tools zur Codegenerierung verwenden, die von diesen Daten abhängen. Sie sollten jedoch den CustomAPI.IsPrivate-Wert auf true festlegen, bevor Sie Ihre Lösung zur Verwendung durch andere ausliefern. Wenn Sie später entscheiden, dass Sie andere Anwendungen zur Verwendung der Nachricht unterstützen möchten, können Sie den CustomAPI.IsPrivate-Wert auf false festlegen.

Weitere Informationen:

• Wann Sie Ihre benutzerdefinierte API privat machen sollten
• Private Nachrichten
• Private Nachrichten können nicht in Plug-Ins verwendet werden

Bekannte Probleme mit benutzerdefinierten APIs

Die benutzerdefinierte API ist jetzt allgemein verfügbar, aber es gibt noch einige damit zusammenhängende Funktionalitäten, die wir noch ändern wollen.

Profiler kann nicht zum Debuggen verwendet werden

Um mit dem Plug-In-Registrierungstool und der Plug-In-Profiler-Lösung zu debuggen, müssen Sie in der Lage sein, einen bestimmten Plug-In-Schritt auszuwählen. Die Implementierung der Hauptstufe für das Plug-in ist derzeit nicht im Tool für die Plug-in-Registrierung verfügbar.

Abhilfe: Registrieren Sie den Plug-In-Typ auf der Stufe PostOperation der für die Custom-API erstellten Nachricht.

Private Nachrichten können nicht in Plug-Ins verwendet werden

Wenn Sie Ihre angepasste API als privat definieren, können Sie diese Nachricht nicht in einem Plug-In verwenden. Weitere Informationen: Private Nachrichten

Für das benutzerdefinierte API-Hauptvorgangs-Plug-In kann keine sichere und unsichere Konfiguration festgelegt werden

Sie können keine sichere oder unsichere Konfiguration in das Hauptvorgangs-Plug-In für die benutzerdefinierte API übergeben.

Problemumgehung : Anstatt das Plug-In mit der benutzerdefinierten API zu verknüpfen, registrieren Sie das Plug-In in der PostOperation-Phase mit dem Plug-In-Registrierungstool (PRT). Auf diese Weise können Sie Konfigurationsdaten im PostOperation-Plug-In-Schritt wie gewohnt angeben.

Um diese Problemumgehung zu verwenden, müssen Sie Ihre benutzerdefinierte API für die für die Aktivierung von synchronen und asynchronen benutzerdefinierten Verarbeitungsschritttypen konfigurieren, wenn Sie die benutzerdefinierte API erstellen. Sie können dies nach der Erstellung nicht ändern.

Nächste Schritte

Erstellen Sie eine benutzerdefinierte API mit dem Plug-In-Registrierungstool

Siehe auch

Custom-APIs erstellen und verwenden
Erstellen Sie eine Custom-API mit Code
Eine benutzerdefinierte API mit Lösungsdateien erstellen
Eigene Nachrichten erstellen
Benutzerdefinierte API-Tabellen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).