> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Executar um script personalizado durante a criação da VM (versão prévia) > Use o recurso em versão prévia VmStartupScript para executar scripts personalizados durante a criação de VMs do PlayFab Multiplayer Servers, permitindo a instalação de agentes e o roteamento de logs. # Executando um script personalizado durante a criação da VM - VmStartupScript (versão prévia) ## Introdução > [!NOTE] > > Este recurso está em versão prévia. Você pode começar a usá-lo hoje e nos enviar seus comentários. As instruções sobre como entrar em contato conosco são fornecidas no final do artigo. Observe que o suporte técnico é limitado durante a versão prévia. O VmStartupScript permite executar um script personalizado nas máquinas virtuais (VMs) usadas no PlayFab Multiplayer Servers (MPS). O MPS é otimizado para a hospedagem de servidores de jogo, facilitando a escala dinâmica do seu título de acordo com a demanda. Para facilitar a personalização rápida de um grande número de servidores durante a inicialização das VMs, o script personalizado pode ser executado em todas as VMs subjacentes que hospedam seus servidores de jogo. Ele pode ser usado para realizar tarefas como instalar software personalizado, modificar configurações de segurança, usar um serviço personalizado para registrar a saída e as métricas dos servidores de jogo e muito mais. > [!NOTE] > > Este é um recurso avançado que deve ser usado com extrema cautela. O script em execução é executado no nível da máquina virtual (VM) com privilégios de administrador (root). Se não for usado corretamente, ele poderá interromper o fluxo normal dos servidores de jogo em execução ou até mesmo impedir que eles sejam executados. O usuário final é responsável pelo conteúdo do script. [https://www.youtube.com/embed/oc-X7rHCwUU](https://www.youtube.com/embed/oc-X7rHCwUU) ## Como usar o VmStartupScript Para usar o recurso VmStartupScript, você precisa fornecer um script personalizado e todo o software relevante (opcional) que planeja instalar. O script começa a ser executado quando a máquina virtual é inicializada. Essa operação ocorre antes que os servidores de jogo sejam iniciados em cada VM. Depois que o script terminar de ser executado com êxito, o serviço MPS prossegue para concluir a inicialização dos servidores de jogo e os coloca no estado **StandingBy**. Para saber mais sobre os diferentes estados do servidor de jogo, consulte [Ciclo de vida de um servidor multijogador](/pt-BR/services/playfab/multiplayer/servers/multiplayer-game-server-lifecycle). Para usar este recurso em um ambiente de produção real, consulte o [Fluxo de trabalho recomendado para desenvolvedores](#recommended-development-workflow) antes de começar. ### Criar um script * Crie um arquivo chamado **PF\_StartupScript.sh** para VMs Linux ou **PF\_StartupScript.ps1** para VMs Windows. * Adicione comandos de configuração/execução ao arquivo. Se precisar, veja algumas [variáveis de ambiente](#environment-variables) usadas com frequência que você pode usar no script. Algumas ações não têm suporte ou fariam com que as VMs não iniciassem com êxito, gerando cobranças indesejadas. Para obter detalhes, consulte a seção [O que não tem suporte](#what-is-not-supported). Para ver exemplos de scripts, consulte [VmStartupScriptGallery](https://github.com/PlayFab/VmStartupScriptGallery). ### Criar e carregar o arquivo zip 1. Reúna em uma pasta todo o software relevante que seu script planeja usar ou chamar. Se o seu script instalar software de terceiros, ele poderá baixá-lo durante a execução, ou o software pode ser incluído no arquivo zip. Ignore esta etapa se não for instalar nada. 2. Crie um arquivo zip (.zip) com o script (.sh ou .ps1) que você criou na seção anterior e com o software reunido na etapa anterior, se necessário. O arquivo de script deve estar na raiz do arquivo zip, e não dentro de um diretório. Além disso, se o arquivo de script não se chamar **PF\_StartupScript.sh** (Linux) ou **PF\_StartupScript.ps1** (Windows), ele não será executado, e os servidores de jogo não iniciarão. 3. Carregue o arquivo zip usando um dos seguintes métodos: * Use o [PlayFab Game Manager](/pt-BR/services/playfab/multiplayer/servers/deploy-using-game-manager#assets-for-builds) * Emita uma solicitação PUT com o cabeçalho \{"x-ms-blob-type": "BlockBlob"} na URL retornada pela chamada à [API GetAssetUploadUrl](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/get-asset-upload-url). * Use os [cmdlets do PowerShell](/pt-BR/services/playfab/multiplayer/servers/deploy-using-powershell-api#upload-an-asset). > [!NOTE] > > Recomendamos incluir no arquivo zip todos os binários e ativos necessários para o seu script, pois isso resultará em uma execução mais rápida e em menos tempo para o MPS disponibilizar seus servidores de jogo. Inclua os ativos da plataforma relevante em que seus servidores de jogo serão executados. Por exemplo, se você usar servidores Linux, deverá incluir pacotes Debian/Ubuntu "amd64". ### Aplicar o script personalizado a novos builds Depois de carregar o arquivo .zip, use a API do MPS para criar um novo build depois de configurar a propriedade **VmStartupScriptAssetReference**. Para obter instruções, consulte [Como criar builds usando a API do MPS](/pt-BR/services/playfab/multiplayer/servers/deploy-using-powershell-api). * Adicione a propriedade **VmStartupScriptConfiguration.VmStartupScriptAssetReference**, que inclui uma referência ao arquivo de ativos carregado. Essa propriedade faz parte de todas as APIs relacionadas a "CreateBuild", como [CreateBuildWithCustomContainer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-custom-container), [CreateBuildWithManagedContainer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-managed-container) e [CreateBuildWithProcessBasedServer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/create-build-with-process-based-server). * Adicione um valor válido para a propriedade **VmStartupScriptAssetReference.FileName**. Esse valor deve ser igual ao nome do seu arquivo de ativos, por exemplo, **vmstartupscriptassets.zip**. * A propriedade **VmStartupScriptAssetReference.MountPath** deve estar vazia, pois não tem suporte no recurso VmStartupScript. > [!NOTE] > > Se você definir um valor para a propriedade **MountPath**, a operação de criação do build falhará. O exemplo de código abaixo cria um build com contêineres Linux e, em seguida, usa o script em **vmstartupscriptassets.zip** para personalizar as VMs: ```csharp theme={null} var request = new CreateBuildWithCustomContainerRequest() { ContainerImageReference = new ContainerImageReference() { ImageName= "testimagename", Tag= "0.1" }, ContainerFlavor = ContainerFlavor.CustomLinux, BuildName = "testbuildwithvmstartupscript", VmSize = AzureVmSize.Standard_D2as_v4, MultiplayerServerCountPerVm = 3, Ports= new List { new Port() { Name= "port", Num= 123, Protocol = ProtocolType.TCP } }, RegionConfigurations = new List { new BuildRegionParams() { Region = "EastUs", StandbyServers = 3, MaxServers = 6 } }, VmStartupScriptConfiguration = new VmStartupScriptParams() { VmStartupScriptAssetReference = new AssetReferenceParams() { FileName = "vmstartupscriptassets.zip" } } }; var result = await PlayFabMultiplayerAPI.CreateBuildWithCustomContainerAsync(request); ``` O VmStartupScript é executado durante o estágio de "Propping" (preparação) da VM e deve terminar com êxito para que os servidores de jogo sejam iniciados. Se falhar (código de saída diferente de 0), a VM não passará para o estado "Running", e você precisará se conectar à VM por RDP/SSH para depurar. Para saber mais, consulte o [Fluxo de trabalho recomendado para desenvolvedores](#recommended-development-workflow). A VM continuará tentando executar o VmStartupScript. ## Considerações especiais ### No Linux, preciso marcar o arquivo PF\_StartupScript.sh como executável? Antes de executar o arquivo de script, o MPS o marca como executável e converte todas as terminações de linha do Windows ("\r\n") para as do Linux ("\n"). Portanto, você não precisa se preocupar com essas duas coisas. ### Variáveis de ambiente Veja a seguir as variáveis de ambiente que você pode usar no seu script de inicialização. | Nome | Descrição | | - | - | | PF\_TITLE\_ID | ID do título do PlayFab | | PF\_BUILD\_ID | ID do build do PlayFab MPS | | PF\_VM\_ID | ID da máquina virtual do MPS | | PF\_REGION | Região do Azure em que a VM está hospedada | | PF\_PUBLIC\_IPV4\_ADDRESS | Endereço IP público da VM | | PF\_FQDN | Nome de domínio totalmente qualificado que corresponde ao IP público da VM | | PF\_SHARED\_CONTENT\_FOLDER\_VM | pasta com conteúdo compartilhado em toda a VM | ### O que não tem suporte Você não deve executar estas ações a partir do seu script, pois há uma grande chance de interromper o ciclo de vida da VM e dos servidores de jogo: * Não bloqueie durante a execução do script de inicialização. O script deve terminar com êxito para que os servidores de jogo sejam criados. Se precisar que algo seja executado em segundo plano, você pode instalá-lo como um serviço systemd no Linux ou como um serviço do Windows. * Não use portas a partir de 30000, pois elas são usadas pelos servidores de jogo, nem a porta 56001, pois ela é usada pelo processo VmAgent (o executável orquestrador de servidores de jogo do MPS). * Não modifique nenhum dos arquivos nos caminhos D: (Windows) ou /mnt (Linux), pois esses arquivos são necessários para a operação do VmAgent (exceto as pastas com conteúdo editável, como `PF_SHARED_CONTENT_FOLDER_VM`). * Você não deve usar o [GSDK](https://github.com/PlayFab/gsdk) de dentro do VmStartupScript ou de um aplicativo iniciado por ele. O GSDK só deve ser usado a partir dos GameServers. * Você não deve reiniciar manualmente a máquina virtual, pois essa operação criará problemas na comunicação com o plano de controle do MPS. ## Portas Ao usar o recurso VmStartupScript, é possível solicitar que várias portas sejam expostas em cada VM. Essas portas podem ser usadas por quaisquer programas iniciados pelo seu script e são diferentes das portas que o MPS abre para seus servidores de jogo. ### Uso Você pode solicitar até cinco portas para cada VM. Para cada porta, você deve especificar o protocolo (TCP ou UDP) e um nome. Veja um exemplo de como solicitar duas portas: ```csharp theme={null} VmStartupScriptConfiguration = new VmStartupScriptParams() { VmStartupScriptAssetReference = new AssetReferenceParams() { FileName = "vmstartupscriptassets.zip" }, PortRequests = new List() { new VmStartupScriptPortRequest() { Name = "port0", Protocol = ProtocolType.TCP }, new VmStartupScriptPortRequest() { Name = "port1", Protocol = ProtocolType.UDP } } } ``` Se você solicitar portas, as seguintes variáveis de ambiente estarão disponíveis para o seu script, para ajudar a obter informações sobre as portas: | Nome | Descrição | | - | - | | PF\_STARTUP\_SCRIPT\_PORT\_COUNT | Número de portas do VmStartupScript | | PF\_STARTUP\_SCRIPT\_PORT\_NAME\_(index) | O nome da porta, conforme descrito na solicitação | | PF\_STARTUP\_SCRIPT\_PORT\_PROTOCOL\_(index) | O protocolo da porta, conforme descrito na solicitação | | PF\_STARTUP\_SCRIPT\_PORT\_INTERNAL\_(index) | A porta à qual seu programa deve se associar na VM | | PF\_STARTUP\_SCRIPT\_PORT\_EXTERNAL\_(index) | A porta aberta no ponto de extremidade externo. Os clientes externos devem usar essa porta para se conectar ao programa que se associa à porta INTERNAL | Por exemplo, para as duas portas solicitadas no script de exemplo acima, você deve esperar encontrar estas variáveis de ambiente no seu VmStartupScript: ```bash theme={null} PF_STARTUP_SCRIPT_PORT_COUNT PF_STARTUP_SCRIPT_PORT_INTERNAL_0 PF_STARTUP_SCRIPT_PORT_EXTERNAL_0 PF_STARTUP_SCRIPT_PORT_NAME_0 PF_STARTUP_SCRIPT_PORT_PROTOCOL_0 PF_STARTUP_SCRIPT_PORT_INTERNAL_1 PF_STARTUP_SCRIPT_PORT_EXTERNAL_1 PF_STARTUP_SCRIPT_PORT_NAME_1 PF_STARTUP_SCRIPT_PORT_PROTOCOL_1 ``` > [!NOTE] > > Assim como nas portas que abrimos para os servidores de jogo, cabe a você autenticar os clientes que se conectam às suas portas. O MPS não fornece nenhum mecanismo de autenticação para essas portas. > [!NOTE] > > Os clientes perceberão que as portas alocadas começam a partir do número 20000. No entanto, recomendamos que você não codifique esse valor nos seus scripts, pois ele pode mudar no futuro; use sempre as variáveis de ambiente para obter as informações corretas das portas. ## Desenvolvimento/depuração Antes de usar o recurso VmStartupScript, recomendamos que você confira estes scripts de exemplo no nosso repositório de código aberto no GitHub ([VmStartupScriptGallery](https://github.com/PlayFab/VmStartupScriptGallery)). Contribuições são bem-vindas! ### Fluxo de trabalho de desenvolvimento recomendado Inicialmente, você deve criar um build de teste com uma única VM. Essa VM deve ter especificações semelhantes às da VM em que você planeja implantar seu build de produção. Quando essa VM única estiver implantada, você poderá se conectar por RDP/SSH, copiar os arquivos necessários e tentar editar/executar o script até que ele funcione. Depois que essa VM estiver em execução e você verificar que seu script se comporta conforme o esperado, você poderá colocar o script e os ativos em um arquivo .zip. Em seguida, você poderá carregá-lo e tentar criar um build com ele. Tente criar novamente um build com uma única VM para economizar custos e aumente a escala quando tiver certeza de que seu script funciona. Se você encontrar problemas para executar seu script, poderá depurar fazendo logon na VM por RDP/SSH e verificando os arquivos **PF\_StartupScriptStdOut.txt** e **PF\_StartupScriptStdErr.txt**, que contêm, respectivamente, os fluxos de saída padrão e de erro padrão do script. Esses arquivos ficam na unidade D: no Windows ou em /mnt no Linux. O script deve ser idempotente, pois há uma chance de ele ser executado mais de uma vez. Por exemplo, se o script tentar baixar um recurso externo e falhar devido a um problema de rede, o MPS repetirá toda a execução do script. ## Suporte O serviço MPS executará o que estiver no seu VmStartupScript. No entanto, a equipe não fornecerá suporte para as ações individuais e os executáveis instalados/executados como parte do script. Durante a versão prévia, obtenha suporte e envie comentários usando os [Fóruns da comunidade do PlayFab](https://community.playfab.com/) e o [Discord](https://aka.ms/msftgamedevdiscord). Se você tiver problemas com algum script do repositório VmStartupScriptGallery ou quiser solicitar um novo, [abra um problema](https://github.com/PlayFab/VmStartupScriptGallery/issues) no GitHub. ## Related topics - [Gerenciar segredos (versão prévia)](/pt-BR/services/playfab/multiplayer/servers/manage-secrets.md) - [Usar o Playtest durante a versão prévia](/pt-BR/publishing/game-publishing/concepts/playtest-preview.md) - [Ferramenta de criação de scripts](/pt-BR/tools/tools-console/wdp/script-authoring-tool.md) - [Escrever CloudScript personalizado](/pt-BR/services/playfab/live-service-management/service-gateway/automation/cloudscript/writing-custom-cloudscript.md) - [Início rápido do Particionamento de Eventos (Versão Prévia)](/pt-BR/services/playfab/data-analytics/export-data/event-partitioning-quickstart.md)