​

이벤트 파이프라인

​

파이프라인 타입

• 텔레메트리 이벤트 파이프라인: 텔레메트리 이벤트만 방출할 수 있으며 Write Telemetry Events REST API를 사용합니다.
• PlayStream 이벤트 파이프라인: PlayStream 이벤트만 방출할 수 있으며 Write Events REST API를 사용합니다.

​

인증 타입

​

엔터티 인증

• namespace: namespace 엔터티는 스튜디오 내 모든 타이틀에 대한 모든 전역 정보를 나타냅니다.
• title: title 엔터티는 해당 타이틀에 대한 모든 전역 정보를 나타냅니다.
• master_player_account: master_player_account는 스튜디오 내 모든 타이틀에서 공유되는 플레이어 엔터티입니다.
• title_player_account: 대부분의 개발자에게 title_player_account는 가장 전통적인 방식으로 플레이어를 나타냅니다.
• character: character 엔터티는 title_player_account의 하위 엔터티입니다.
• group: group 엔터티는 다른 엔터티에 대한 컨테이너입니다. 현재 플레이어와 캐릭터로 제한됩니다.

​

텔레메트리 키 인증

1. PlayFab Game Manager를 통해 생성 및 관리되는 문자열로 구성되는 텔레메트리 키.
2. 이벤트를 업로드하는 데 사용되어야 하는 올바른 서비스 구성이 무엇인지 SDK에 알려주는 PFServiceConfigHandle. 서비스 구성 핸들은 SDK 초기화 중에 PFServiceConfigCreateHandle을 호출하여 생성됩니다.

​

이벤트 파이프라인 구성

• maxEventsPerBatch: PlayFab에 쓰기 전에 배치되는 최대 이벤트 수.
• maxWaitTimeInSeconds: 파이프라인이 미완성 배치를 보내기 전에 대기하는 최대 시간.
• pollDelayInMs: 파이프라인이 이벤트 버퍼를 비운 후 다시 읽기 위해 대기하는 시간.
• compressionLevel: 압축 알고리즘에서 사용되는 압축 수준을 정의합니다. 압축에 대한 자세한 내용은 _GZIP 압축_을 참조하세요.
• retryOnDisconnect: 이벤트 파이프라인은 연결 손실로 인해 실패한 이벤트 전송을 다시 시도합니다. 텔레메트리 이벤트 파이프라인에만 사용할 수 있습니다.
• bufferSize: 파이프라인 버퍼의 이벤트 양 제한.

​

기본값

​

GZIP 압축

​

이벤트 핸들러

• PFEventPipelineBatchUploadSucceededEventHandler: 이름에서 알 수 있듯이, PlayFab에 성공적으로 업로드된 모든 이벤트를 수신합니다.
• PFEventPipelineBatchUploadFailedEventHandler: 파이프라인 재시도 로직을 거친 후 실패한 모든 이벤트를 수신합니다.

​

파이프라인 생성 예제

1. 엔터티 인증을 사용한 텔레메트리 이벤트 파이프라인 생성 개발자가 텔레메트리 이벤트를 보내고 싶고 텔레메트리 키 인증을 사용할 필요가 없는 경우, PFEventPipelineCreateTelemetryPipelineHandleWithEntity API가 다음 예제와 같이 이 목적에 부합합니다:
   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   
   이 예제는 엔터티 인증을 사용하는 텔레메트리 이벤트 파이프라인을 만드는 방법을 보여주며 핸들러가 없습니다. 이는 파이프라인이 이벤트를 발생시키고 결과에 대해 잊는다는 것을 의미합니다.
2. 텔레메트리 키 인증을 사용한 텔레메트리 이벤트 파이프라인 생성 개발자가 텔레메트리 이벤트를 보내고 싶고 텔레메트리 키 인증을 사용할 필요가 있는 경우, PFEventPipelineCreateTelemetryPipelineHandleWithKey API가 다음 예제와 같이 이 목적에 부합합니다:
   void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
       {
           "myTelemetryKey",                   // telemetryKey
           serviceConfigHandle,                // serviceConfigHandle
       };
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
           &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   
   이 예제는 엔터티 인증을 사용하지 않는 텔레메트리 이벤트 파이프라인을 만드는 방법을 보여줍니다. 이벤트 파이프라인은 텔레메트리 키를 사용하여 이벤트 업로드를 시작하며, 나중에 엔터티를 추가할 수 있는 가능성이 있습니다. 엔터티 인증으로 전환 또는 엔터티 업데이트를 참조하세요.
3. PlayStream 이벤트 파이프라인 생성 개발자가 PlayStream 이벤트를 보내고 싶은 경우, PFEventPipelineCreatePlayStreamPipelineHandle API가 다음 예제와 같이 이 목적에 부합합니다:
   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreatePlayStreamPipelineHandle(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           nullptr,                            // eventPipelineBatchUploadedEventHandler
           nullptr,                            // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   
   이 예제는 엔터티 인증을 사용하는 PlayStream 이벤트 파이프라인이 어떻게 생성되는지 보여주며 핸들러가 없습니다. 이는 파이프라인이 이벤트를 발생시키고 결과에 대해 잊는다는 것을 의미합니다.
4. 이벤트 핸들러를 사용하는 이벤트 파이프라인 이 예제는 파이프라인 생성 API에 이벤트 핸들러가 어떻게 제공될 것인지 보여줍니다.
   void CALLBACK OnBatchUploadedHandler(void* context, PFUploadedEvent const* const* events, size_t eventsCount)
   {
       // Handle response
   }
   
   void CALLBACK OnBatchUploadFailedHandler(void* context, HRESULT hr, const char* errorMessage, PFEvent const* const* events, size_t eventsCount)
   {
       // Handle response
   }
   
   void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
   {
       PFEventPipelineHandle handle;
   
       HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
           entityHandle,                       // entityHandle
           taskQueueHandle,                    // queue
           OnBatchUploadedHandler,             // eventPipelineBatchUploadedEventHandler
           OnBatchUploadFailedHandler,         // eventPipelineBatchFailedEventHandler
           nullptr,                            // handlerContext
           &handle                             // eventPipelineHandle
       );
   
       if (FAILED(hr))
       {
           printf("Failed creating event pipeline: 0x%x\r\n", hr);
           return;
       }
   }
   

​

이벤트 방출

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEvent myEvent
    {
        nullptr,
        "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEntityKey pfEntityKey{ "my-unique-ID", "external" };  // Note the "external" value

    PFEvent myEvent
    {
        &pfEntityKey,
        "custom.playfab.events.PlayFab.Test.EventsWithTelemetryKey",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

• E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

​

엔터티 인증으로 전환 또는 엔터티 업데이트

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

void EventPipelineUpdateEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineAddUploadingEntity(
        handle,                 // eventPipelineHandle
        entityHandle            // entityHandle
    );

    if (FAILED(hr))
    {
        printf("Failed adding uploading entity: 0x%x\r\n", hr);
        return;
    }
}

​

텔레메트리 키 인증으로 전환

void EventPipelineRemoveEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineRemoveUploadingEntity(
        handle                  // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed removing uploading entity: 0x%x\r\n", hr);
        return;
    }
}

​

파이프라인 구성 업데이트

void EventPipelineUpdateConfiguration(PFEventPipelineHandle handle)
{
    uint32_t maxEvents = 10;
    uint32_t maxWaitTime = 5;
    uint32_t pollDelay = 50;
    PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
    bool retryOnDisconnect = true;
    size_t bufferSize = 2048;

    PFEventPipelineConfig eventPipelineConfig
    {
        &maxEvents,             // maxEventsPerBatch
        &maxWaitTime,           // maxWaitTimeInSeconds
        &pollDelay,             // pollDelayInMs
        &compressionLevel,      // compressionLevel
        &retryOnDisconnect,     // retryOnDisconnect
        &bufferSize,            // bufferSize
    };

    HRESULT hr = PFEventPipelineUpdateConfiguration(
        handle,                 // eventPipelineHandle
        eventPipelineConfig     // eventPipelineConfig
    );

    if (FAILED(hr))
    {
        printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
        return;
    };
}

​

무효 / 비활성화된 텔레메트리 키

​

파이프라인 핸들 수명 주기

• PFEventPipelineCloseHandle: 파이프라인 핸들을 닫습니다. 파이프라인에 대한 마지막 핸들이 닫히면 파이프라인이 파괴되고 남은 버퍼링된 이벤트가 플러시됩니다.
• PFEventPipelineDuplicateHandle: 파이프라인 핸들을 복제합니다. 원본과 복제된 핸들 모두 PFEventPipelineCloseHandle로 독립적으로 닫아야 합니다.

// Duplicate a handle for use in another component
PFEventPipelineHandle duplicatedHandle;
HRESULT hr = PFEventPipelineDuplicateHandle(originalHandle, &duplicatedHandle);

// When done, close both handles independently
PFEventPipelineCloseHandle(duplicatedHandle);
PFEventPipelineCloseHandle(originalHandle);

​

참고 항목

• 이벤트 파이프라인 튜토리얼