As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Reserve contatos com efemérides personalizadas
## Visão geral do
Ao usar efemérides personalizadas (TLE, OEM ou elevação de azimute), você pode reservar contatos usando a API. [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) Esta seção descreve dois fluxos de trabalho comuns para reservar contatos e considerações importantes para garantir o sucesso do agendamento de contatos.
AWS Ground Station antenas são recursos compartilhados entre vários clientes. Isso significa que, mesmo que uma janela de contato apareça disponível quando você lista contatos, outro cliente pode reservá-la antes de você. Portanto, é crucial verificar se seu contato atinge o `SCHEDULED` estado após a reserva e implementar o monitoramento adequado das mudanças no estado do contato.
**Importante**
Para efemérides de elevação de azimute, o `satelliteArn` parâmetro pode ser omitido da `ReserveContact` solicitação e você deve fornecer o ID da efeméride. `trackingOverrides` Para efemérides de TLE e OEM, você ainda precisa fornecer o. `satelliteArn`
## Fluxos de trabalho de reservas de contatos
Há dois fluxos de trabalho principais para reservar contatos com efemérides personalizadas:
1. *List-then-reserve fluxo de trabalho:* primeiro liste as janelas de contato disponíveis usando [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html), depois selecione e reserve uma janela específica. Essa abordagem é útil quando você deseja ver todas as oportunidades disponíveis antes de fazer uma seleção.
1. *Fluxo de trabalho de reserva direta:* reserve diretamente um contato para uma janela de tempo específica sem primeiro listar os contatos disponíveis. Essa abordagem é útil quando você já sabe o horário de contato desejado ou está trabalhando com horários predeterminados.
Ambos os fluxos de trabalho são válidos e a escolha depende de seus requisitos operacionais. As seções a seguir fornecem exemplos de cada abordagem.
## Fluxo de trabalho 1: liste os contatos disponíveis e reserve
Esse fluxo de trabalho primeiro consulta as janelas de contato disponíveis e, em seguida, reserva uma janela específica. Isso é útil quando você deseja ver todas as oportunidades disponíveis antes de fazer uma seleção.
### Exemplo: Listar e reservar com efemérides de elevação de azimute
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="AzEl Ephemeris for Contact",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
contacts = ground_station_client.list_contacts(
# Note: satelliteArn is omitted for azimuth elevation ephemeris
groundStation="Ohio 1",
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
startTime=datetime(2024, 3, 15, 10, 0, 0, tzinfo=timezone.utc),
endTime=datetime(2024, 3, 15, 10, 15, 0, tzinfo=timezone.utc),
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
trackingOverrides={
"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}
},
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
### Exemplo: Listar e reservar com efemérides de TLE
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="TLE Ephemeris for Contact",
satelliteId=satellite_id,
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=7),
priority=1, # Higher priority than default ephemeris
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24075.54719794 .00000075 00000-0 26688-4 0 9997",
"tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906",
"validTimeRange": {
"startTime": datetime.now(timezone.utc),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
}
]
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
start_time = datetime.now(timezone.utc) + timedelta(hours=1)
end_time = start_time + timedelta(days=1)
contacts = ground_station_client.list_contacts(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
groundStation="Hawaii 1",
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
startTime=start_time,
endTime=end_time,
statusList=["AVAILABLE"],
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
# Note: trackingOverrides is optional for TLE/OEM
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
## Fluxo de trabalho 2: reserva de contato direto
Esse fluxo de trabalho reserva diretamente um contato sem primeiro listar as janelas disponíveis. Essa abordagem é útil quando você já sabe o horário de contato desejado ou está implementando o agendamento automatizado.
### Exemplo: reserva direta com efemérides de elevação de azimute
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Define contact window
contact_start = datetime(2024, 3, 20, 14, 0, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 20, 14, 15, 0, tzinfo=timezone.utc)
# Create azimuth elevation ephemeris for the specific contact time
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": contact_start.isoformat(),
"validTimeRange": {
"startTime": contact_start.isoformat(),
"endTime": contact_end.isoformat(),
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted for azimuth elevation
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact_start,
endTime=contact_end,
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact: {reservation['contactId']}")
```
### Exemplo: reserva direta com efemérides da TLE
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Define contact window (based on predicted pass)
contact_start = datetime(2024, 3, 21, 10, 30, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 21, 10, 42, 0, tzinfo=timezone.utc)
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact TLE Ephemeris",
satelliteId=satellite_id,
enabled=True,
expirationTime=contact_end + timedelta(days=1),
priority=1,
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24080.50000000 .00000075 00000-0 26688-4 0 9999",
"tleLine2": "2 25994 98.2007 35.6589 0001234 89.2782 18.9934 14.57114995112000",
"validTimeRange": {
"startTime": (contact_start - timedelta(hours=1)).isoformat(),
"endTime": (contact_end + timedelta(hours=1)).isoformat(),
},
}
]
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact_start,
endTime=contact_end,
# Note: trackingOverrides is optional for TLE
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
```
## Monitorando mudanças no estado do contato
Depois de reservar um contato, é importante monitorar seu estado para garantir que ele faça a transição `SCHEDULED` e seja notificado sobre quaisquer problemas. AWS Ground Station emite eventos para a Amazon EventBridge para todas as mudanças de estado de contato.
Os estados de contato seguem este ciclo de vida:
+ `SCHEDULING`- O contato está sendo processado para agendamento
+ `SCHEDULED`- O contato foi agendado com sucesso e será executado
+ `FAILED_TO_SCHEDULE`- O contato não pôde ser agendado (estado do terminal)
Para obter mais informações sobre estados de contato e ciclo de vida, consulte. [Entenda o ciclo de vida do contato](contacts.lifecycle.md)
### Implementando o monitoramento do estado de contato com EventBridge
Para monitorar as mudanças no estado do contato em tempo real, você pode configurar uma EventBridge regra da Amazon que aciona uma função Lambda sempre que um contato da Ground Station muda de estado. Essa abordagem é mais eficiente e escalável do que pesquisar o status do contato.
#### Etapas de implementação
1. Crie uma função Lambda para processar eventos de mudança de estado de contato
1. Crie uma EventBridge regra que corresponda aos eventos de mudança de estado de contato da Ground Station
1. Adicione a função Lambda como destino para a regra
#### Exemplo de manipulador de funções Lambda
Para ver um exemplo completo de uma função Lambda que processa eventos de mudança de estado de contato, consulte o `GroundStationCloudWatchEventHandlerLambda` recurso no `AquaSnppJpssTerraDigIF.yml` CloudFormation modelo. Esse modelo está disponível no bucket Amazon S3 de integração do AWS Ground Station cliente. Para obter instruções sobre como acessar esse modelo, consulte a [Juntando tudo](examples.pbs-data-dataflow-endpoint.md#examples.pbs-dataflow-endpoint.putting-it-together) seção do exemplo de endpoint de fluxo de dados.
#### EventBridge configuração de regras
A EventBridge regra deve usar o seguinte padrão de evento para corresponder a todas as mudanças de estado de contato da Ground Station:
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"]
}
```
Para filtrar somente por estados específicos (por exemplo, falhas), você pode adicionar um filtro de detalhes:
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"],
"detail": {
"contactStatus": [
"FAILED_TO_SCHEDULE",
"FAILED",
"AWS_FAILED",
"AWS_CANCELLED"
]
}
}
```
Para obter instruções detalhadas sobre a criação de EventBridge regras com alvos Lambda, consulte [Criação de regras que reagem a eventos](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) no Guia EventBridge do usuário da Amazon.
### Configurando EventBridge regras para automação
Você pode criar EventBridge regras para responder automaticamente às mudanças no estado do contato. Por exemplo:
+ Enviar notificações quando um contato não consegue agendar
+ Acione as funções do Lambda para preparar recursos quando um contato entra `PREPASS`
+ Registre as conclusões de contatos para fins de auditoria
Para obter informações detalhadas sobre como configurar EventBridge regras para AWS Ground Station eventos, consulte[Automatize AWS Ground Station com eventos](monitoring.automating-events.md).
## Práticas recomendadas e considerações
### Lidando com conflitos de agendamento
Como as AWS Ground Station antenas são recursos compartilhados, uma janela de contato que aparece disponível em `ListContacts` pode ser reservada por outro cliente antes que você possa reservá-la. Para lidar com isso:
1. Sempre verifique o status do contato após a reserva
1. Implemente a lógica de repetição com janelas de tempo alternativas
1. Considere reservar contatos com bastante antecedência, quando possível
1. Use EventBridge eventos para monitorar os `FAILED_TO_SCHEDULE` estados
### Tempo de validação de efemérides
Lembre-se de que as efemérides devem estar em vigor antes `ENABLED` que você possa usá-las para reservar contatos. O processo de validação normalmente leva de alguns segundos a alguns minutos, dependendo do tipo e tamanho da efeméride. Sempre verifique o status das efemérides antes de tentar reservar contatos.
### Considerações sobre o tempo de contato
Ao usar efemérides personalizadas:
+ Certifique-se de que suas efemérides cubram toda a duração do contato
+ [Para efemérides de elevação de azimute, verifique se os ângulos mantêm a antena acima da máscara do local durante todo o contato](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html)
+ Considere os prazos de expiração das efemérides ao agendar contatos futuros
### Diferenças de API por tipo de efeméride
A `ReserveContact` API se comporta de forma diferente dependendo do tipo de efeméride:
| Tipo de efemérides | É necessário o SatellitEarn | Substituições de rastreamento necessárias |
| --- | --- | --- |
| TELHA | Sim | Não (opcional) |
| OEM | Sim | Não (opcional) |
| Elevação do azimute | Não (opcional) | Sim |