빠른 시작: Azure Functions를 사용하여 PlayFab CloudScript 작성
이 빠른 시작에서는 Visual Studio Code, Azure Functions C#, Unity C#과 함께 Azure Functions를 사용하여 CloudScript를 작성합니다. 이 가이드를 마치면 새 CloudScript를 규칙, 예약된 작업에 연결하거나 클라이언트 코드에서 호출할 수도 있습니다.
필수 조건
PlayFab C# CloudScript를 시작하는 데 필요한 몇 가지 단계가 있습니다.
- Visual Studio Code 빠른 시작: Visual Studio Code를 사용하여 Azure Functions 프로젝트 만들기를 방문하고 설정이 완료되면 여기로 돌아오세요. 다음 필수 조건은 해당하는 빠른 시작 가이드에서 다룹니다.
- Azure 계정. Azure 계정 등록은 무료입니다.
- Azure 구독
- Azure Portal에 구성된 Functions 앱 리소스
- Azure Functions를 사용하여 CloudScript의 대기 시간을 최소화하려면 미국 서부, 미국 서부 2, or 미국 서부 3 Azure 지역에 배치합니다.
- 보안 참고 사항: 보안 관점에서 PlayFab에서 지정된 함수 암호만 사용하고 다른 소스에서 동일한 함수를 호출하는 데 사용하지 않도록 해야 합니다.
- 보안 참고사항: 대기 중인 함수의 경우 큐 트리거에 사용되는 큐에 대해 별도의 스토리지 계정을 설정해야 합니다.
- PlayFab 계정.
참고 항목
PlayFab Azure Functions는 Azure Functions V2 런타임 이상 및 .NET Core 2 이상을 사용할 수 있습니다. 최신 버전(현재 Azure Functions V4 및 .NET 6)을 사용하는 것이 좋습니다.
Azure 함수 만들기
기본 “HelloWorld” 예제 함수를 만듭니다. 이렇게 하는 방법은 Visual Studio Code를 사용하여 첫 번째 함수 만들기 가이드에서 확인할 수 있습니다. PlayFab 변수를 사용하는 코드 예제는 아래의 PlayFab 함수 컨텍스트, 변수 및 서버 SDK 사용 섹션을 참조하세요.
Important
“Visual Studio Code를 사용하여 첫 번째 함수 만들기” 가이드에서는 Azure 함수의 권한 부여 수준을
Anonymous로 설정하도록 안내합니다. 테스트를 간소화하기 위해 이렇게 합니다.프로덕션 환경에서는 익명 권한 부여를 사용하면 누구나 함수 엔드포인트를 호출할 수 있게 되므로 대부분의 경우 이렇게 하면 안 됩니다. PlayFab 환경에서 함수를 제대로 보호하려면
Function수준 권한 부여를 사용하는 것이 좋습니다.함수를 만들고 배포한 후 자동화>클라우드 스크립트로 이동하여 페이지의 오른쪽 모서리에서 함수 등록 버튼을 선택합니다.
이름에 함수의 이름을 입력합니다. 함수 URL에 함수의 HTTP 트리거 URL을 입력합니다. URL은 빠른 시작: Visual Studio Code를 사용하여 Azure에서 함수 만들기의 "Azure에서 함수 실행" 섹션에 표시된 대로 Azure 함수 리소스의 바로 가기 메뉴에서 찾을 수 있습니다. Azure 함수가
Function수준 인증을 사용하는 경우 URL에 인증 키가 포함됩니다.
Azure 함수 배포에 대한 자세한 내용은 Visual Studio Code에서 Azure Functions 배포를 참조하세요.
PlayFab 타이틀에서 Azure Functions를 사용하여 CloudScript 사용 및 호출
이 가이드의 예제 코드는 Unity C# 및 Azure Function C# 코드로 작성합니다.
이제 함수가 등록되었으므로 PlayFab API를 사용하여 내부에서 해당 함수를 호출할 수 있습니다.
Visual Studio Code의 HTTP 요청을 사용하여 함수 호출
REST 클라이언트 확장 프로그램을 사용하면 Visual Studio 내에서 함수를 호출할 수 있습니다.
@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"]
}
이 코드를 확장자가 .http인 Visual Studio Code의 파일에 붙여넣은 후 LoginWithCustomID 함수 아래에서 요청 보내기를 선택하여 플레이어의 엔터티 토큰을 가져온 다음 아래에서 함수를 호출하기 위한 LoginWithCustomID. GetObjects를 호출하면 Azure 함수가 플레이어를 연결한 개체가 표시되어야 합니다.
Unity에서 함수 호출
Unity에서 이 코드를 사용하여 함수를 호출할 수 있습니다.
//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 컨텍스트, 변수 및 서버 SDK
Azure Functions를 사용하여 CloudScript를 사용할 때 한 가지 이점은 PlayStream 이벤트 및 플레이어 프로필 컨텍스트가 Azure 함수에 자동으로 전달된다는 것입니다. CloudScript를 호출하면 함수의 호출 시나리오에 따라 컨텍스트를 수신합니다. 예를 들어 컨텍스트는 PlayStream Action에 의해 트리거되었는지 또는 클라이언트에서 직접 호출되었는지에 따라 다릅니다. 여기에는 CloudScript가 호출된 엔터티 프로필 및 CloudScript를 호출하는 데 사용되는 PlayStream 이벤트와 같은 정보가 포함됩니다.
- 패키지 관리자를 통해 PlayFab SDK를 설치해야 합니다. 이렇게 하려면 Visual Studio Code에서 터미널 또는 CMD 콘솔을 열고 다음을 입력합니다.
dotnet add package PlayFabAllSDK -
PlayFab.Samples의 구현을 포함하는 CS2AFHelperClasses.cs 파일을 포함해야 합니다. - 스크립트 실행은 여러 메서드(API, 예약된 작업, PlayStream 이벤트, 세그먼트 입력 및 Exit 메서드)를 통해 발생할 수 있습니다. 실행 컨텍스트는 CloudScript를 구현하는 데 중요합니다. 스크립트의 컨텍스트를 사용하는 방법에 대한 자세한 내용은 CloudScript 컨텍스트 모델 사용 자습서를 참조하세요.
아래의 HelloWorld 예제를 첫 번째 Azure 함수로 사용할 수 있습니다. 엔터티 API를 호출하고 인증된 플레이어에게 인사말을 반환합니다. 클래식 서버 API는 비슷한 방식으로 호출할 수 있습니다. 그러나 호출을 하려면 타이틀 비밀 키를 지정해야 합니다. 비밀 키는 애플리케이션 설정에 저장하고 Environment.GetEnvironmentVariable() 메서드를 사용하여 검색할 수 있습니다.
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 };
}
}
}
이 예제에서 호출자의 CurrentPlayerId를 기존 CloudScript 구현에서와 같이 사용할 수 있습니다.
FunctionParameters 필드에 전달하는 매개 변수는 args에서 사용할 수 있습니다. 그러나 Visual Studio Code를 사용하여 첫 번째 함수 만들기 가이드의 Hello World 예제와 달리 매개 변수가 쿼리 문자열아 아니라 POST 본문에 전달됩니다.
PlayFab SDK에서 HelloWorld Azure 함수를 호출하려면 ExecuteFunction을 사용합니다.
자동화 규칙의 Azure Functions
규칙 및 예약된 작업을 만들어 Azure Functions를 호출할 수도 있습니다. 이는 표준 CloudScript와 동일한 방식으로 작동합니다. 규칙 또는 예약된 작업을 만들려면 자동화>규칙 또는 자동화>예약된 작업으로 이동하세요.
- 새 규칙을 선택합니다.
- 그룹 이름을 입력합니다.
- 이 규칙이 트리거되는 이벤트 유형을 선택하세요.
- 작업 추가
- 작업 드롭다운에서 Azure 함수 실행을 선택합니다.
등록한 사용 가능한 Azure 함수 목록을 드롭다운 목록에서 사용할 수 있습니다.
Azure 함수 디버깅
이제 Azure Functions를 사용하면 로컬로 또는 Azure Portal에서 CloudScript를 디버그할 수 있습니다. 포털 디버깅에 대한 자세한 내용은 Azure Portal에서 Azure Functions를 사용하여 CloudScript 디버깅을 참조하세요. 로컬 디버깅을 설정하는 방법을 알아보려면 Azure Functions를 사용한 Cloudscript의 로컬 디버깅을 참조하세요.
실행 제한
Azure Functions에 대한 CloudScript 호출에는 제한 시간 제한이 있습니다. 웹훅을 실행하는 데 너무 오래 걸리면 PlayFab에서 요청 시간이 초과됩니다. 코드가 제한 시간을 초과하지 않을 만큼 충분히 빠르게 실행할 수 있는지 확인합니다.
| Source | 동작 유형 | 제한(초) |
|---|---|---|
| playfab, api | HTTP 요청 | 10 |
| PlayStream V2 | HTTP 요청 | 10 |
| 예약된 작업 | HTTP 요청 | 4.5. |
| PlayStream V1 | HTTP 요청 | 1 |
| 큐 함수 | 큐 페이로드 | 1 |