API API API API API API API API API API API API API API API API API API API API API API API Criando uma chave de serviço

Criando uma chave de serviço com a API

Este tópico descreve o procedimento da API para criar uma chave de serviço, incluindo como obter o ID da Port (productUid) e criar um VXC com uma chave de serviço.

Para uma visão geral das chaves de serviço, consulte Configurando chaves de serviço e Gerenciando chaves de serviço. Para mais informações sobre APIs de chave de serviço, consulte Service Keys (API Documentation).

Pré-requisitos

Acesso ao Megaport Portal.
Uma Port, MCR, ou MVE na rede da Megaport.
Você tem um token de acesso válido. Para mais informações, consulte Criando uma chave de API.

Como obter o productUid para a Port

No Postman, clique em Product Details (Detalhes do Produto) na navegação à esquerda e selecione GET Product List (GET Lista de Produtos).
Clique em Send (Enviar).
Nos detalhes do produto retornados, localize o valor de productUid da Port para a qual você deseja criar a chave de serviço.

Este exemplo usa a seguinte Port:
```
"productName": "CoreSite LA1" in "city": "Los Angeles" 
with "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303"
```

Criando uma chave de serviço

Depois de localizar o valor de productUid do produto para o qual você deseja criar a chave de serviço, você pode usar a API da Megaport para criar a chave de serviço.

Para criar uma chave de serviço

No Postman, clique em Connections (Conexões) na navegação à esquerda e selecione Service Keys > POST Generate Service Key (Chaves de serviço > POST Gerar chave de serviço).

Copie o productUid do seu on-ramp (Port) e atualize o Body.

Para este exemplo, o valor do productUid da Port é 8611b645-ea50-46eb-b400-1c2fb858a303.

{
    "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
    "description": "Documentation Service Key - Single Use",
    "active": true,
    "_set_singleUse_to_false_to_make_service_key_multiUse": true,
    "singleUse": true,
    "maxSpeed": "500",
    "preApproved": true,
    "vlan": 3,
    "validFor": {
         "_make_start_timestamp_equal_to_now": 1608506197135,
         "start": 1608506197135,
         "_make_end_timestamp_equal_to_1_month_forward": 1612015200000,
         "end": 1612015200000
    }
}

Especifique parâmetros adicionais no Body, por exemplo, rate limit (maxSpeed), por quanto tempo a chave será válida (validFor) e se você precisa de uma chave de uso único ("singleUse": true) ou chave de múltiplos usos ("singleUse": false). As datas são inseridas no formato de data de timestamp UNIX. Você pode usar ferramentas como https://www.epochconverter.com/ ou https://it-tools.tech/date-converter para determinar o valor correto a inserir.

Somente para chaves de uso único, especifique um ID de VLAN (vlan).

Este é o ID de VLAN para o B-End. A Megaport verifica se o ID de VLAN solicitado está disponível. Quando um cliente usa esta chave de serviço para criar uma conexão com seu Port, ele pode especificar um ID de VLAN para o A-End.

Para mais informações sobre IDs de VLAN, consulte Gerenciando IDs de VLAN.
Quando terminar, clique em Send (Enviar) para fazer a solicitação.
```
POST /v2/service/key
```

Uma resposta bem-sucedida passa na validação e tem um status 200 OK.

{
    "message": "New service key [106e38ae-eb59-415f-ac81-526a5299851d] generated",
    "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
    "data": {
        "key": "106e38ae-eb59-415f-ac81-526a5299851d",
        "createDate": 1712277262872,
        "companyId": 1153,
        "companyUid": "160208ae-01e4-4cb9-8d57-03a197bd47a8",
        "companyName": "Megaport Lab",
        "description": "Documentation Service Key - Single Use",
        "productId": 193076,
        "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
        "productName": "My new Port",
        "vlan": 3,
        "maxSpeed": 500,
        "preApproved": true,
        "singleUse": true,
        "lastUsed": null,
        "active": true,
        "validFor": {
            "start": 1608506197135,
            "end": 1612015200000
        },
        "expired": true,
        "valid": false,
        "promoCode": null,
        "productDto": {
            "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303",
            "productName": "My new Port",
            "portSpeed": 1000,
            "locationId": 60,
            "vxcPermitted": true,
            "companyUid": "160208ae-01e4-4cb9-8d57-03a197bd47a8",
            "companyName": "Megaport Lab",
            "connectType": "DEFAULT",
            "productId": 193076,
            "productType": "MEGAPORT",
            "provisioningStatus": "LIVE",
            "createDate": 1712268634020,
            "createdBy": "0b367492-186d-47ab-96e0-34ca03d29dcd",
            "terminateDate": null,
            "liveDate": 1712268694790,
            "market": "US",
            "costCentre": "Optional finance reference",
            "usageAlgorithm": "NOT_POST_PAID",
            "marketplaceVisibility": false,
            "secondaryName": null,
            "lagPrimary": false,
            "lagId": null,
            "aggregationId": null,
            "contractStartDate": 1712268694807,
            "contractEndDate": 1714831200000,
            "contractTermMonths": 1,
            "associatedVxcs": [],
            "associatedIxs": [],
            "attributeTags": {},
            "virtual": false,
            "buyoutPort": false,
            "locked": false,
            "adminLocked": false,
            "diversityZone": null,
            "nserviceId": 521477,
            "cancelable": true
        }
    }
}

A nova chave de serviço agora aparece no Megaport Portal.

Editando ou desabilitando a chave

Você pode editar os detalhes de uma chave de serviço ou desabilitá-la permanentemente.

Pode haver várias razões pelas quais você gostaria de desabilitar a chave. Por exemplo, você cria uma chave de serviço para um de seus Ports e a compartilha com seu cliente, mas antes que seu cliente crie uma conexão com a chave de serviço, o Port fica indisponível e você deseja impedir que seu cliente use essa chave de serviço.

Para editar ou desabilitar a chave de serviço

No Postman, abra a pasta Connections (Conexões) na navegação esquerda e selecione Service Keys > PUT Update Service Key (Chaves de Serviço > PUT Atualizar Chave de Serviço).
Edite os detalhes da chave de serviço conforme necessário.
Para desabilitar permanentemente a chave de serviço, defina o parâmetro active como false.

Compartilhando a chave

Você pode compartilhar a service key como preferir, como por e-mail ou mensagens.

Nota

O destinatário da service key não pode alterar ou modificar os parâmetros da service key.

Criando um VXC com uma chave de serviço

Depois de receber uma chave de serviço, você pode criar um VXC com a chave de serviço para conectar o on-ramp A-End definido na chave de serviço e seu on-ramp B-End.

Para criar um VXC com uma chave de serviço

No Postman, abra a pasta Connections (Conexões) na navegação esquerda e selecione Service Keys > POST Create VXC with a Service Key (Chaves de Serviço > POST Criar VXC com uma Chave de Serviço).
Especifique os detalhes de configuração no Body da solicitação.
- productUid - Insira o productUid do Port na sua localização da Megaport location.
- bEnd: productUid - Insira a localização productUid da consulta da chave de serviço.
- serviceKey- Insira a chave de serviço completa.
- ratelimit - Especifique um ratelimit até o limite máximo de taxa definido na chave de serviço.
- term - Especifique o prazo do contrato para o VXC. Valores válidos são 1, 12, 24, 36, 48 e 60 meses. Se você não especificar term ao solicitar um VXC, o padrão será 1 (Sem Prazo Mínimo).
- shutdown - Você pode desligar temporariamente e reabilitar o VXC. Valores válidos são true (desligar) e false (habilitado). Se não fornecido, o padrão é false (habilitado).
- promoCode - Você pode inserir um código promocional para o pedido de serviço. O código não é validado, portanto, se o código não existir ou não funcionar para o serviço, a chamada ainda será bem-sucedida.
- vlan - (Opcional) VLAN A-End preferida. Especifique um ID de VLAN não utilizado para esta conexão.
  
  Este deve ser um ID de VLAN único neste Port e pode variar de 2 a 4093. Se você especificar um ID de VLAN que já está em uso, o sistema exibe o próximo número de VLAN disponível. O ID de VLAN deve ser único para prosseguir com o pedido. Se você não especificar um valor, a Megaport atribuirá um.
  
  A VLAN B-End para o término do lado do provedor será automaticamente preenchida com base na chave de serviço.
```
{
    "productUid": "7fba50bb-ac35-465b-9b8b-9a6d7335ec7a",
    "associatedVxcs": [
        {
            "productName": "VXC from service key",
            "rateLimit": 100,
            "term": 12,
            "shutdown": false,
            "promoCode": "promox3mnthfree2",
            "serviceKey": "106e38ae-eb59-415f-ac81-526a5299851d",
            "aEnd": {
                "vlan": 2
            },
            "bEnd": {
                "productUid": "8611b645-ea50-46eb-b400-1c2fb858a303"
            }
        }
    ]
}
```
Quando terminar, clique em Send (Enviar) para fazer a solicitação.
```
POST /v3/networkdesign/buy
```
Dica

Para testar sua solicitação antes de fazer o pedido e ver detalhes de preços, use o endpoint /v3/networkdesign/validate com a mesma configuração de Body.

Uma resposta bem-sucedida passa na validação e tem um status 200 OK.

{
  "message": "VXC [399f0fd8-8a69-4e15-abdb-537b0cb8a858] created. ",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy",
  "data": [
    {
      "createDate": 1610140443499,
      "vxcOrderId": 55791,
      "payerMegaPortId": 74841,
      "nonPayerMegaPortId": 39950,
      "payerMegaPortName": "My LA API Port",
      "nonPayerMegaPortName": "BNE5-01-10G",
      "payerCompanyId": 15,
      "nonPayerCompanyId": 28,
      "payerLocationId": 60,
      "nonPayerLocationId": 44,
      "salesId": null,
      "payerCompanyName": "Megaport Lab",
      "nonPayerCompanyName": "6YS",
      "payerMegaPortNsId": 167551,
      "nonPayerMegaPortNsId": 90147,
      "payerVlanId": 2,
      "nonPayerVlanId": 373,
      "payerInnerVlanId": null,
      "nonPayerInnerVlanId": null,
      "payerApproverName": "Test Name",
      "payerApproverId": 32278,
      "nonPayerApproverName": null,
      "nonPayerApproverId": null,
      "payerApproval": 1610140443263,
      "nonPayerApproval": 1610140443308,
      "fixedTerm": true,
      "duration": 1,
      "rollover": true,
      "serviceName": "from My LA API Port to BNE5-01-10G",
      "payerStatus": "APPROVED",
      "nonPayerStatus": "APPROVED",
      "speed": 100,
      "distanceBand": "ZONE",
      "intercapPath": "",
      "awsId": null,
      "promoCode": null,
      "rateType": "MONTHLY",
      "vxcJTechnicalServiceId": 74842,
      "vxcJTechnicalServiceUid": "399f0fd8-8a69-4e15-abdb-537b0cb8a858",
      "provisionDate": 1610140443232,
      "orderType": "NEW",
      "monthlyDiscountAmount": null,
      "discountMonths": null,
      "amazonDirectConnectConfigDto": null,
      "amsixConnectConfigDto": null,
      "webAirProvItem": null,
      "sdrcProvItem": null,
      "rate": null,
      "setup": null,
      "asn": null,
      "bgpPassword": null,
      "usageAlgorithm": "POST_PAID_HOURLY_SPEED_LONG_HAUL_VXC",
      "costCentre": null,
      "azureServiceKey": null,
      "oracleVirtualCircuitId": null,
      "serviceKey": "106e38ae-eb59-415f-ac81-526a5299851d",
      "connectType": "DEFAULT",
      "payerConfig": {},
      "nonPayerConfig": {},
      "attributeTags": {},
      "fullyApproved": true
    }
  ]
}

Após solicitar o VXC com a chave de serviço, uma notificação é enviada para a empresa à qual você está se conectando, e a empresa destinatária pode aceitar ou rejeitar a chave. Ela não pode alterar a chave, mas pode solicitar modificações nos parâmetros da chave de serviço antes de aceitá-la.

O VXC criado com a chave de serviço aparecerá no Megaport Portal para ambas as empresas.