Schnellstart: Schreiben eines PlayFab CloudScript mit Azure Functions

  • Artikel

In dieser Schnellstartanleitung schreiben Sie ein CloudScript mit Azure Functions mit Visual Studio Code, Azure Functions C# und Unity C#. Nach Abschluss dieses Leitfadens können Sie Ihr neues CloudScript mit Regeln oder geplanten Aufgaben verknüpfen oder sogar aus Ihrem Clientcode aufrufen.

Voraussetzungen

Für die ersten Schritte mit PlayFab C# CloudScript sind einige Schritte erforderlich.

  • Besuchen Sie den Visual Studio Code-Schnellstart: Erstellen eines Azure Functions-Projekts mit Visual Studio Code, und kehren Sie hierher zurück, sobald Sie eingerichtet sind. Die folgenden Voraussetzungen werden in ihrem Schnellstarthandbuch behandelt:
    • Ein Azure-Konto. Die Registrierung für ein Azure-Konto ist kostenlos.
    • Ein Azure-Abonnement
    • Eine im Azure-Portal konfigurierte Functions-App-Ressource
      • Um die Latenz Ihrer CloudScript-Instanz mithilfe von Azure Functions sie in den Azure-Regionen USA, Westen2 oder USA, Westen 3 platzieren.
      • Sicherheitshinweis: Aus Sicherheitsgründen sollten Sie sicherstellen, dass Sie nur ein bestimmtes Funktionsgeheimnis mit PlayFab und nicht zum Aufrufen derselben Funktion aus einer anderen Quelle verwenden.
      • Sicherheitshinweis: Für Funktionen in der Warteschlange sollten Sie ein eigenes Speicherkonto für die Warteschlangen einrichten, die für den Warteschlangentrigger verwendet werden.
  • Ein PlayFab-Konto .

Notiz

PlayFab Azure Functions kann die Azure Functions V2-Runtime oder höher und .NET Core 2 oder höher verwenden. Es wird empfohlen, die neueste Version (derzeit Azure Functions V4 und .NET 6) zu verwenden.

Erstellen einer Azure-Funktion

  1. Erstellen Sie eine einfache "HelloWorld"-Beispielfunktion. Wie Dies funktioniert, erfahren Sie im Leitfaden Erstellen Ihrer ersten Funktion mithilfe von Visual Studio Code. Ein Codebeispiel mit PlayFab-Variablen finden Sie im Abschnitt unter PlayFab-Funktionskontext, Variablen und verwenden der Server-SDKs.

    Wichtig

    Im Leitfaden "Erstellen Ihrer ersten Funktion mit Visual Studio Code" werden Sie angewiesen, die Autorisierungsebene Ihrer Azure-Funktion auf festzulegen Anonymous. Dies geschieht, um Tests zu vereinfachen.

    In einer Produktionsumgebung sollten Sie in den meisten Fällen keine anonyme Autorisierung verwenden, da sie es jedem ermöglicht, Ihren Funktionsendpunkt aufzurufen. Um Ihre Funktion in der PlayFab-Umgebung ordnungsgemäß zu schützen, empfiehlt es sich, die Levelautorisierung zu verwenden Function .

  2. Nachdem Sie Ihre Funktion erstellt und bereitgestellt haben, wechseln Sie zu Automation>Cloud Script , und wählen Sie in der oberen rechten Ecke der Seite die Schaltfläche Funktion registrieren aus.

    Registrieren der CloudScript-Funktion

  3. Geben Sie unter Name einen Anzeigenamen für Ihre Funktion ein. Geben Sie unter Funktions-URL die HTTP-Trigger-URL der Funktion ein. Die URL finden Sie im Kontextmenü der Azure-Funktionsressource, wie im Abschnitt "Ausführen der Funktion in Azure" unter Schnellstart: Erstellen einer Funktion in Azure mit Visual Studio Code gezeigt. Wenn Ihre Azure-Funktion die Ebenenautorisierung verwendet Function , enthält die URL den Autorisierungsschlüssel.

Weitere Informationen zum Bereitstellen von Azure-Funktionen finden Sie unter Bereitstellen von Azure Functions aus Visual Studio Code.

Verwenden und Aufrufen von CloudScript mit Azure Functions aus Ihrem PlayFab-Titel

Der Beispielcode in diesem Leitfaden ist in Unity C# & Azure Function C#-Code geschrieben.

Nachdem Ihre Funktion registriert wurde, können Sie diese Funktion mithilfe von PlayFab-APIs von innen aufrufen.

Aufrufen Ihrer Funktion mithilfe von HTTP-Anforderungen von Visual Studio Code

Mit der REST-Clienterweiterung können Sie die Funktion in Visual Studio aufrufen.

@titleId =  ????? # Enter your title ID here
@baseUrl = https://{{titleId}}.playfabapi.com

###
# @name LoginWithCustomID
POST {{baseUrl}}/Client/LoginWithCustomID
Accept-Encoding: gzip
Content-Type: application/json

{
  "CustomId": "demo",
  "CreateAccount": true,
  "TitleId": "{{titleId}}"
}

@entityToken = {{LoginWithCustomID.response.body.$.data.EntityToken.EntityToken}}
@entity = {{LoginWithCustomID.response.body.$.data.EntityToken.Entity}}

###
# @name ExecuteFunction
POST {{baseUrl}}/CloudScript/ExecuteFunction
Accept-Encoding: gzip
Content-Type: application/json
X-EntityToken: {{entityToken}}

{
  "FunctionName": "HelloWorld"
}

###
# @name GetObjects
POST {{baseUrl}}/Object/GetObjects
Accept-Encoding: gzip
Content-Type: application/json
X-EntityToken: {{entityToken}}

{
  "Entity": {{entity}},
  "Objects": ["obj1"]
}

Nachdem Sie diesen Code in eine Datei in Visual Studio Code mit der Http-Erweiterung eingefügt haben, sollten Sie unter der Funktion LoginWithCustomID die Option Anforderung senden auswählen können, um das Entitätstoken eines Spielers abzurufen, und dann unter LoginWithCustomID, um Ihre Funktion aufzurufen. Beim Aufrufen von GetObjects sollte das Objekt angezeigt werden, das ihre Azure-Funktion dem Player angefügt hat.

Aufrufen Ihrer Funktion aus Unity

Sie können diesen Code in Unity verwenden, um Ihre Funktion aufzurufen.

//This snippet assumes that your game client is already logged into PlayFab.

using PlayFab;
using PlayFab.CloudScriptModels;

private void CallCSharpExecuteFunction()
{
    PlayFabCloudScriptAPI.ExecuteFunction(new ExecuteFunctionRequest()
    {
        Entity = new PlayFab.CloudScriptModels.EntityKey()
        {
            Id = PlayFabSettings.staticPlayer.EntityId, //Get this from when you logged in,
            Type = PlayFabSettings.staticPlayer.EntityType, //Get this from when you logged in
        },
        FunctionName = "HelloWorld", //This should be the name of your Azure Function that you created.
        FunctionParameter = new Dictionary<string, object>() { { "inputValue", "Test" } }, //This is the data that you would want to pass into your function.
        GeneratePlayStreamEvent = false //Set this to true if you would like this call to show up in PlayStream
    }, (ExecuteFunctionResult result) =>
    {
        if (result.FunctionResultTooLarge ?? false)
        {
            Debug.Log("This can happen if you exceed the limit that can be returned from an Azure Function, See PlayFab Limits Page for details.");
            return;
        }
        Debug.Log($"The {result.FunctionName} function took {result.ExecutionTimeMilliseconds} to complete");
        Debug.Log($"Result: {result.FunctionResult.ToString()}");
    }, (PlayFabError error) =>
    {
        Debug.Log($"Opps Something went wrong: {error.GenerateErrorReport()}");
    });
}

PlayFab CloudScript-Kontext, Variablen und Server-SDKs

Ein Vorteil der Verwendung von CloudScript mit Azure Functions besteht darin, dass der PlayStream-Ereignis- und Playerprofilkontext automatisch an die Azure-Funktion übergeben wird. Beim Aufruf von CloudScript erhalten Sie den Kontext entsprechend dem Aufrufszenario der Funktion. Der Kontext unterscheidet sich beispielsweise davon, ob er durch eine PlayStream-Aktion ausgelöst oder direkt vom Client aufgerufen wurde. Dies umfasst Informationen wie das Entitätsprofil, in dessen Auftrag cloudScripts aufgerufen wurde, und möglicherweise die PlayStream-Ereignisse, die zum Aufrufen von CloudScript verwendet werden.

  1. Sie müssen das PlayFab SDK über den Paket-Manager installieren. Öffnen Sie dazu das Terminal oder die CMD-Konsole in Visual Studio Code, und geben Sie Folgendes ein: dotnet add package PlayFabAllSDK
  2. Sie müssen die CS2AFHelperClasses.cs-Datei einschließen, die die Implementierung von enthält. PlayFab.Samples
  3. Die Ausführung eines Skripts kann über verschiedene Methoden erfolgen (APIs, Geplante Aufgaben, PlayStream-Ereignis, Segmenteingabe und Exit-Methode). Der Kontext der Ausführung ist wichtig, um CloudScript zu implementieren. Ausführliche Informationen zur Verwendung des Kontexts des Skripts finden Sie im Tutorial Verwenden von CloudScript-Kontextmodellen .

Sie können das unten gezeigte HelloWorld-Beispiel als erste Azure-Funktion verwenden. Es ruft eine Entitäts-API auf und gibt eine Begrüßung an den authentifizierten Player zurück. Klassische Server-APIs können auf ähnliche Weise aufgerufen werden. Allerdings müsste man den geheimen Titelschlüssel angeben, um den Aufruf durchführen zu können. Der geheime Schlüssel kann in den Anwendungseinstellungen gespeichert und mithilfe der Environment.GetEnvironmentVariable() -Methode abgerufen werden.

using PlayFab;
using PlayFab.Samples;
using PlayFab.DataModels;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace PlayFabCS2AFSample.HelloWorld
{
    public static class HelloWorld
    {
        [FunctionName("HelloWorld")]
        public static async Task<dynamic> Run(
            [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            FunctionExecutionContext<dynamic> context = JsonConvert.DeserializeObject<FunctionExecutionContext<dynamic>>(await req.ReadAsStringAsync());

            dynamic args = context.FunctionArgument;

            var message = $"Hello {context.CallerEntityProfile.Lineage.MasterPlayerAccountId}!";
            log.LogInformation(message);

            dynamic inputValue = null;
            if (args != null && args["inputValue"] != null)
            {
                inputValue = args["inputValue"];
            }

            log.LogDebug($"HelloWorld: {new { input = inputValue} }");

            // The profile of the entity specified in the 'ExecuteEntityCloudScript' request.
            // Defaults to the authenticated entity in the X-EntityToken header.
            var entityProfile = context.CallerEntityProfile;

            var api = new PlayFabDataInstanceAPI(
                new PlayFabApiSettings
                {
                    TitleId = context.TitleAuthenticationContext.Id
                },
                new PlayFabAuthenticationContext
                {
                    EntityToken = context.TitleAuthenticationContext.EntityToken
                }
            );

            var apiResult = await api.SetObjectsAsync(
                new SetObjectsRequest
                {
                    Entity = new EntityKey
                    {
                        Id = entityProfile.Entity.Id,
                        Type = entityProfile.Entity.Type
                    },
                    Objects = new List<SetObject> {
                    new SetObject
                    {
                        ObjectName =  "obj1",
                        DataObject = new
                        {
                            foo = "some server computed value",
                            prop1 = "bar"
                        }
                    }
                }
                });

            return new { messageValue = message };
        }
    }
}

Im Beispiel ist der CurrentPlayerId des Aufrufers wie in unserer herkömmlichen CloudScript-Implementierung verfügbar. Parameter, die Sie im FunctionParameters Feld übergeben, sind in den Argumenten verfügbar. Im Gegensatz zum Hallo Welt Beispiels unter Erstellen Ihrer ersten Funktion mithilfe von Visual Studio Code werden Parameter jedoch im POST-Text anstelle der Abfragezeichenfolge übergeben.

Um die HelloWorld-Azure-Funktion aus einem PlayFab SDK aufzurufen, verwenden Sie ExecuteFunction.

Azure Functions in Automatisierungsregeln

Azure Functions können auch aufgerufen werden, indem Regeln und geplante Aufgaben erstellt werden. Dies funktioniert auf die gleiche Weise wie unser Standard CloudScript. Um eine Regel oder eine geplante Aufgabe zu erstellen, wechseln Sie zu Automationsregeln> oderAutomation>Scheduled Tasks.

  • Wählen Sie Neue Regel aus.
  • Geben Sie einen Namen für Ihre Regel ein.
  • Wählen Sie den Ereignistyp aus, für den diese Regel ausgelöst wird.
  • Hinzufügen einer Aktion
  • Wählen Sie in der Dropdownliste Aktion die Option Azure-Funktion ausführen aus.

Eine Liste der verfügbaren Azure Functions, die Sie registriert haben, ist in der Dropdownliste verfügbar.

Konfigurieren der Regel für Azure Functions

Debuggen Ihrer Azure-Funktion

Mit Azure Functions haben Sie jetzt die Möglichkeit, CloudScript lokal oder im Azure-Portal zu debuggen. Weitere Informationen zum Debuggen im Portal finden Sie unter Debuggen von CloudScript mithilfe von Azure Functions mit dem Azure-Portal. Informationen zum Einrichten des lokalen Debuggens finden Sie unter Lokales Debuggen für Cloudscript mit Azure Functions.

Ausführungsgrenzwerte

CloudScript-Aufrufe an Azure Functions haben Timeoutlimits. Wenn die Ausführung Ihres Webhooks zu lange dauert, tritt für die Anforderung in PlayFab ein Timeout auf. Stellen Sie sicher, dass Ihr Code schnell genug ausgeführt werden kann, um unter den Timeoutgrenzwerten zu bleiben.

Quelle Aktionstyp Grenzwert (Sekunden)
PlayFab-API HTTP-Anforderung 10
PlayStream V2 HTTP-Anforderung 10
Geplante Aufgabe HTTP-Anforderung 4.5
PlayStream V1 HTTP-Anforderung 1
Warteschlangenfunktion Warteschlangennutzlast 1