Benutzerdefinierte APIs erstellen und verwenden

Verwenden Sie Custom-APIs, um Ihre eigenen APIs in Dataverse zu erstellen. Sie können eine oder mehrere Operationen 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 Custom Process Action und Custom-API finden Sie unter Vergleich Custom Process Action und Custom-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 delegiert wird Dataverse 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 sehr schnell eine benutzerdefinierte API erstellen. Oder Sie können Ihre eigene Erfahrung aufbauen, um eine benutzerdefinierte API zu erstellen.
Mit Lösungsdateien Wenn Sie Application Lifecycle Management (ALM)-Tools 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 Custom-API-Daten in Tabellen gespeichert werden, unterstützen wir nicht das Erstellen einer modellbasierten App für diese Tabellen.

Es gibt mehrere Tools, die von der Community erstellt und unterstützt werden, um mit der benutzerdefinierten API zu arbeiten:

Custom-API-Anpassung

Beim Erstellen von Custom-API und den zugehörigen Anfrageparametern und Antworteigenschaften ist es wichtig zu verstehen, dass diese API-Definitionen standardmäßig angepasst werden können. Dies 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 Custom-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.

Einstellung ist anpassbare verwaltete Eigenschaft

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

Weitere Informationen Verwaltete Eigenschaften

Fügen Sie zusätzliche 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 Custom-API hinzugefügt werden. Zusätzliche Abfrageparameter können jedoch nicht erforderlich gemacht werden. Wenn Sie benutzerdefinierte Verarbeitungsschritte auf Ihrer benutzerdefinierten API zulassen, können diese zusätzlichen Parameter und Eigenschaften, die der ursprünglichen Definition hinzugefügt wurden, von anderen Plug-Ins verwendet werden, 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.

Wählen Sie einen benutzerdefinierten Verarbeitungsschritttyp aus

Die folgende Tabelle beschreibt, welche benutzerdefinierte API Benutzerdefinierter Verarbeitungsschritttyp (AllowedCustomProcessingStepType) du solltest benutzen.

Option Verwenden des s
Keine Wenn der für diese benutzerdefinierte API festgelegte Plug-In-Typ die einzige Logik ist, die auftritt, wenn dieser Vorgang ausgeführt wird.
Sie gestatten keinem anderen Entwickler, zusätzliche Schritte zu registrieren, die zusätzliche Logik auslösen, das Verhalten dieses Vorgangs ändern oder den Vorgang abbrechen können.
Verwenden Sie dies, 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.
Dies ist die empfohlene Option, wenn Sie das Geschäftsereignismuster verwenden. Ein Geschäftsereignis wird einen Auslöser in Power Automate erstellen, 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 dies 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 dies, 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 Bindungstyp (BindingType) du solltest benutzen.

Option Verwenden des s
Global Wenn die Operation 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.

Wählen Sie Juristische Person oder EntityCollection, erfordert dies, dass Sie den vollständig qualifizierten 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 müssen sie nicht 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:

Wann eine Funktion erstellen

Die benutzerdefinierte API-Eigenschaft Ist Funktion steuert, ob die benutzerdefinierte API eine Funktion oder Aktion ist. In OData ist eine Funktion eine Operation, die über HTTP-Anfrage 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-Anfragen einfacher nur über Ihren Browser testen, aber die Länge der URL, die gesendet werden kann, ist begrenzt, normalerweise etwa 2000 Zeichen. 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 dieselbe Operation ausführt und alle Parameterdaten im Hauptteil mit POST-Anfrage ü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 Verbraucher beeinträchtigen.

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

Die Ist privat-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.

Dies bedeutet nicht, dass andere Entwickler Ihre Nachricht nicht verwenden können, wenn sie davon wissen und eine Anfrage zur Verwendung verfassen können. Einstellung der Ist privat-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 Ihrem verwaltete Lösung versenden, sollten Sie Ist privat zu wahr festlegen.

Weitere Informationen:

Sichern Sie Ihre benutzerdefinierte API mit einem Privileg

Legen Sie die benutzerdefinierte API-Eigenschaft Berechtigungsname ausführen (ExecutePrivilegeName) auf den Namen des Privilegs, um es anzufordern. 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 Hauptoperationslogik 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 dies als Testschritt ausführen, aber alle Ausgabeparameterwerte geben die Standardwerte für den Typ zurück, da kein Code zum Festlegen vorhanden ist.

Verwenden Sie eine benutzerdefinierte API in einem Workflow

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 darf keine Funktion sein, die Ist Funktion muss falsch 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
    • Integer
    • Money
    • Picklist
    • String
    • GUID

    Die folgenden Anforderungsparameter- oder Antworteigenschaftstypen dürfen nicht verwendet werden:

    • Entity
    • EntityCollection
    • StringArray

Aufrufen von angepassten APIs

Eine benutzerdefinierte API erstellt eine neue Nachricht, die wie jede andere Operation über die Web-API oder das Organization Service SDK aufgerufen werden kann.

Aufrufen von angepassten APIs von der Web-API

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"
}

Gebundene Aktion

Diese Aktion 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

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:

Aufrufen von Custom-APIs aus dem Organisationsdienst

Sie können wählen, ob Sie früh- oder spät-gebundenen Code verwenden, um Ihre angepasste API aufzurufen. Verwenden Sie das CrmSvcUtil-Tool zum Generieren von Hilfsanforderungs- und Antwortklassen, um die Anforderungsparameter und Antworteigenschaften Ihrer benutzerdefinierten API bereitzustellen.

Für spät gebundenen Code oder für eine Custom-API, die Sie als privat markiert haben, erstellen Sie eine OrganizationRequest mit dem eindeutigen Namen Ihrer Custom-API und fügen Sie Parameter mit Namen hinzu, die mit den eindeutigen Namen der Anfrageeigenschaften ü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 eine benutzerdefinierte API mit dem Namen myapi_EscalateCase ist an die Incident-Tabelle 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 Dienst Organisation verwenden.

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.

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.

Das Folgende 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 Basissprache enthält und für jede aktivierte zusätzliche 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.

Zeigt an, wie Beschriftungen lokalisiert werden.

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 Labels im Code festzulegen, anstatt den oben beschriebenen manuellen Prozess zu verwenden, können Sie die SetLocLabels-Meldung entweder über die Web-API SetLocLabels Action oder den Organisationsdienst SetLocLabelsRequest 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
        }
    ]
}

Response

HTTP/1.1 204 No Content

Lokalisierte Werte abrufen

Verwenden Sie zum Abrufen der lokalisierten Beschriftungen die RetrieveLocLabels-Nachricht entweder über die Web-API RetrieveLocLabels-Funktion oder den Organisationsdienst RetrieveLocLabelsRequest.

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 Ausführungsberechtigungsnamen (ExecutePrivilegeName)-Eigenschaft aufweist, gibt es derzeit keine unterstützte Möglichkeit, eine neue Berechtigung nur für diese API zu erstellen. Dies 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 werden dafür generiert. Zum 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: Das ist nicht möglich. 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 Anfrageparameter oder die Antwort-Eigenschaften.

F: Wie kann ich meine privaten Nachrichten verwenden, wenn sie nicht im Web-API-$metadata service-Dokument 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:

Bekannte Probleme mit benutzerdefinierten APIs

Custom-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

Nächste Schritte

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

Siehe auch

Benutzerdefinierte APIs erstellen und verwenden
Eine benutzerdefinierte API mit Code erstellen
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).